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Preface 


Organization 








This book is intended for system programmers who use the IBM data 
management access methods—other than VSAM (virtual storage access 
method)—to process data sets. This book does not cover such specialized 
applications as time sharing option (TSO), graphics, teleprocessing, optical 


character readers, optical reader — sorters, and magnetic character readers. These 


specialized applications are described in separate publications listed in JBM 
System/370 and 4300 Processors Bibliography, GC20-0001. 


To learn about VSAM or to write programs that create and process VSAM data 


sets, see: 


e MVS/Extended Architecture Catalog Administration Guide, GC26-4041, 
which describes how to create master and user catalogs 


e MVS/Extended Architecture VSAM Administration Guide, GC26-4015, 
which describes how to create VSAM data sets 


e MVS/Extended Architecture Integrated Catalog Administration: Access 


Method Services Reference, GC26-4019, and MVS/Extended Architecture 


VSAM Catalog Administration: Access Method Services Reference, 


GC26-4075, which describe the access method services commands used to 


manipulate VSAM data sets 


e MVS/Extended Architecture VSAM Administration: Macro Instruction 


Reference, GC26-4016, which describes how to code the macro instructions 


required with VSAM data sets 


This publication has 15 chapters and 4 appendixes: 


e Chapter 1, “Introduction to Data Administration” on page 1, provides an 


overview of data set processing, including a description of four different 
access methods, and a discussion of data set identification. 


e Chapter 2, “Data Set Storage” on page 5, discusses the characteristics of 


data sets that are stored on direct access and magnetic tape devices. 


¢ Chapter 3, “Record Formats” on page 13, discusses the considerations for 
creating and processing records within the various kinds of record formats. 
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e Chapter 4, “Selecting an Access Method” on page 35, gives an overview of ! 
basic and sequential access methods in data management, and compares the ew 
functions and performance of each. 


¢ Chapter 5, “Specifying a Data Control Block and Initializing Data Sets” on 
page 41, discusses how to specify a DCB and how to open and close data 
sets. This chapter also discusses managing buffer pools and handling data set 
volumes. 


e Chapter 6, “Accessing Records in Data Sets” on page 61, discusses how to 
use GET and PUT or READ and WRITE macros to access data records. 
This chapter also discusses analyzing input and output errors. 


¢ Chapter 7, “DCB Exit Routines” on page 75, discusses user-written exit 
routines and the parameter lists they use. 


e Chapter 8, “Spooling and Scheduling Data Sets” on page 105, discusses how 
to route data through the input/output streams of the job entry subsystem 
(JES). 


@ Chapter 9, “Processing a Sequential Data Set” on page 109, discusses 
managing sequential data sets and buffers. 


e Chapter 10, “Processing a Partitioned Data Set” on page 131, discusses the 
advantages and restrictions of partitioned data sets. 


e Chapter 11, “Processing a Direct Data Set” on page 149, discusses the tasks 
required to process BDAM data sets. 


e Chapter 12, “Processing an Indexed Sequential Data Set” on page 159, 
discusses the organization of and the access techniques for ISAM data sets. 


¢ Chapter 13, “Generation Data Groups” on page 193, discusses the reasons 
for using generation data groups and how to specify them. 


e Chapter 14, “I/O Device Control Macros” on page 201, discusses the macro 
instructions that control input and output devices. 


e Chapter 15, “Protecting Data” on page 205, discusses password and 
Resource Access Control Facility (RACF) protection of non-VSAM data 
sets. 


e Appendix A, “Direct Access Labels” on page 209, discusses the standard 
label formats used on direct access volumes. 


e Appendix B, “Control Characters” on page 213, discusses the use of an 
optional control character to control card punches and pmninters. 
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Appendix C, “Allocating Space on Direct Access Volumes” on page 217, 
discusses methods of estimating capacities and space requirements on direct 
access devices. 


Appendix D, “ISO/ANSI/FIPS Record Control Word and Segment Control 


Word” on page 223, discusses the translation of ISO/ANSI/FIPS record 
control words and ISO/ANSI/FIPS segment control words. 


Prerequisite Knowledge 


To use this book efficiently, you should be familiar with: 


Assembler language 


Job control language 


Required Publications 


You should be familiar with the information presented in the following 
publications: 


Related Publications 


Assembler H Version 2 Application Programming: Guide, SC26-4036 


Assembler H Version 2 Application Programming: Language Reference, 
GC26-4037 


MVS/Extended Architecture JCL User's Guide, GC28-1351 


MVS/Extended Architecture JCL Reference, GC28-1352 


Within the text, references are made to the publications listed below: 











Short Title Publication Title Order Number 


Assembler H V2 


Application Application Programming: 
Programming: Guide 
Guide 


Assembler H V2 


Application Application Programming: 
Programming: Language Reference 
Language 


Reference 








SC26-4036 






Assembler H Version 2 











Assembler H Version 2 GC26-4037 
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Short Title Publication Title Order Number 


Data MVS/Extended Architecture GC26-4014 | 












Administration: Data Administration: Macro 
Macro Instruction Instruction Reference 
Reference 

























Debugging MVS/Extended Architecture LC28-1164! 
Handbook Debugging Handbook, | LC28-1165 
Volumes | through 5 LC28-1166 

LC28-1167 







Device Support Facilities User's 
Guide and Reference 


Device Support 


LC28-1168 
Facilities User’s 
Guide and 


GC35-0033 
Reference | 
IBM 3262 Model 5 | JBM 3262 Model 5 Printer GA24-3936 
Printer Product Product Description 
Description 

























IBM 3800 Pnnting | /BM 3800 Printing Subsystem GC26-3846 
Subsystem Programmer's Guide 

Programmer’s 

Guide 


























IBM 3800 Printing | JBM 3800 Printing Subsystem SH35-0061 
Subsystem Models 3 and 8 Programmer's 

Programmer’s Guide 

Guide 












IBM 3890 Document Processor 
Machine and Programming 
Description 


IBM 3890 
Document 
Processor Machine 
and Programming 
Description 


IBM 4245 Printer 
Model 1 
Component 
Description and 
Operator’s Guide 


IBM 4248 Printer IBM 4248 Printer Model 1 
Model 1 Description 


GA33-1541 
GA24-3927 
Description 
Initialization and MVS/Extended Architecture GC28-1149 
Tuning System Programming Library: 
Initialization and Tuning 
JCL User’s Guide MVS/Extended Architecture GC28-1351 
| | JCL User's Guide 
JCL Reference MVS/Extended Architecture GC28- 1352 
JCL Reference 


Note: 















GA24-3612 
IBM 4245 Printer Model | 


Component Description and 
Operator's Guide 








1 All five volumes may be ordered under one order number, LBOF-1015. 
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Short Title Publication Title Order Number 


Magnetic Tape MVS/Extended Architecture GC26-4145 
Labels and File Magnetic Tape Labels and File 

Structure Structure Administration 

Administration 


Open/Close/EOV MVS/Extended Architecture LY 26-3892 
Logic Open/Close/EOV Logic 


OS/VS IBM 3886 OS/VS IBM 3886 Optical GC24-5101 
Optical Character Character Reader Model | 

Reader Model 1 Reference 

Reference 















OS/VS Mass OS/VS Mass Storage System GC35-0011 
Storage System (MSS) Planning Guide 
(MSS) Planning 
Guide 
OS/VS Mass OS/VS Mass Storage Systern GC35-0016 
Storage System (MS'S') Services: General 

SH35-0036 
IBM 3525 Card 


(MSS) Services: Information 
GC21-5097 
Punch 






























OS/VS Mass Storage System 
(MSS) Extensions Services: 
Reference 











Programming Support for the 
IBM 3505 Card Reader and 
the IBM 3525 Card Punch 


Programming 
Support for the 
IBM 3505 Card 
Reader and the 


















Supervisor Services 
and Macro 





Instructions 





OS/VS Mass 
Storage System 
| | System Programming Library: 
Service Aids | 
GC28-1154 
' Instructions 
| System Codes MVS/Extended Architecture — | GC28-1157 
| Message Library: System 
= Codes | 


General 

(MSS) Extensions 
Services: Reference 
RACEF General Resource Access Control GC28-0722 
Information Facility (RACF): General | : 
Manual Information Manual 

MVS/Extended Architecture 

System Programming Library: 
System — Data MVS/Extended Architecture ~GC26-4010 
Administration _System— Data Administration 
System Generation | MVS/Extended Architecture GC26-4009 

: Installation: System Generation 


Information 
Service Aids | MVS/Extended Architecture GC28-1159 
Supervisor Services and Macro 
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System Macros and | MVS/Extended Architecture 
Facilities = System Programming Library: 

: Macros and Facilities, Volumes 
l and 2 


System Messages MVS/Extended Architecture 
Message Library: System 
Messages, Volumes | and 2 
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Short Title Publication Title Order Number 


GC28-1376 

and 

GC28- 1377 

Utilities MVS/Extended Architecture GC26-4018 
Data Administration: Utilities | 























Summary of Changes 


| Release 1.2 Library Update, January 1987 


| Service Changes 


Information has been added, corrected, or deleted to reflect technical service 
changes. 


Release 1.2, February 1984 


New Device Support 


This publication, formerly titled MVS/Extended Architecture Data Management 
Services, is now titled MVS/Extended Architecture Data Administration Guide. 
The publication has been reorganized for ease of use. 


The IBM 3800 Pnnting Subsystem Model 3 is now supported in Model 1 
compatibility mode. 


Modifications have been made to the SETPRT macro to support the IBM 4248, 
3262 Model 5, and 4245 printers. 


Note: The IBM 3262 Model 5 printer is afforded the same support as that 
provided for the IBM 4248 printer. However, the use of an IBM 3262 Model 5 
printer dictates that entries exist in the IBM 4248 printer UCS Image Table for 
the IBM 3262 Model 5 printer band(s)/alias(es) used on the host system. These 
image table entries must be generated by the user as part of the IBM 3262 Model 
5 installation procedure. 


Information to support the IBM 3800 Printing Subsystem Model 3 in full 


function and Model | compatibility mode has been added to the SYNAD 
parameter of the DCB and SETPRT macros. 


Summary of Changes 1X 








X MVS/XA Data Administration Guide 








he men 


ff \ 
{ 5 
| 
, FE 
\ 
\ 7 
ra, 
DS 
‘i « \ 
\ Wy ‘ 
MS et 











Contents 





Chapter 1. Introduction to Data Administration ..................2.2... 1 
Overview or DataSet. Processin®: .i.<6-4.65-4 Aw dca/acw hd Gad wed ae elem we oer ] 
Identityine DataSets dacs Os aoe oe teh eS Sa Seb wee EES ER ed 3 
Chapter:2.. Data Set:Storave). «54:5 4403 6G oe 5.4 cee soe Oe eee oleae 5 
Direct ANCCESs. VOIMINES: 3.5.6 cigs otek 5 oe PO ESOS AEE RARE 5 
Track: Charactenstics: «is 4.255 wets. tea dh Sok PR Re a BAe Re ee 6 
MASNetIC: Fae: VOIUMIES.. fb ccdeviiion sy gritos but dione 8 @ tw as ent hai pet OK 8 
Cataloome Data Sets) ty so a twye equa wn sek ah ERO RE ROS awl ee 9 
Entering a Data Set Name in the Catalog ....................000.4 10 
Chapter’3:.. Record: Formats: 2:44 4.605 fatasions biik Seles aS SANS OHES AEK 13 
Fixed-Length Records, Standard Format ...................0005. 14 
Fixed-Length Records, ISO/ANSI/FIPS Tapes ................... 15 
Vanrabie-|engtnRecOics : 65 ¢e.aa- ews ok eee eo Se eee 17 
Variable-Length Records—Format-V .......... 0.0.00 2c eee eens 18 
ISO/ANSI/FIPS Vanable-Length Records—Format D .............. 23 
ISO/ANSI/FIPS Variable-Length Spanned Records—Format-DS or 
POEMalsD BS: «3.sace oe ssehee dain ek eee PIS eee 24 
Undefined-Length Records .................004.. acta a ery ies Zt 
Record Format—Device Type Considerations ..................0000% 28 
NMaeneic Lape 2.2 25d a eine as Oe hee toi ed a ere 29 
Card Reader and PUunen: cau 2G wee dee eerie eh eee ees ts 30 
Printer? -sa-cas EMG AS Secon Sodas Ursa ai ee ead as RGN, Ee eae ede ae as arene aes 31 
IDIFECHACCESS TIS VIC Ss Sis) a en tk So oe a AS geet eBags peat Sb Oat ee Bed 33 
Chapter 4. Selecting an Access Method ............ 0.000 ee eee eens 35 
OVELVIEW OL ACCESS: MIELDOUS: - iin!) V6 BASES eee Gens Baw ls dts Po we Redd 35 
Basic Direct Access Method (BDAM) ................20 002s 36 
Basic Indexed Sequential Access Method (BISAM) ................ 37 
Basic Partitioned Access Method (BPAM) ...................20.. 37 
Basic Sequential Access Method (BSAM) ...................004. 38 
Queued Indexed Sequential Access Method (QISAM)  .............. 38 
Queued Sequential Access Method (QSAM) .................004. 39 
Chapter 5. Specifying a Data Control Block and Initializing Data Sets .... 41 
selecting: Data Set-Opuons: S-2...0¢.0 0 soe edd elec esed Hee Sw ei Ges 43 
DCD: Patanicters: 2452.05.24. 68 Bead Ale 6 Se ee RSS Sake Skee ees 43 
DD Statement: Parameters: <2 .¢.2c4 sans foe eke Ge Se ee 45 
Chanesing the DEB. 4 p0.4 etoes owed oe Ste thee OSes Gee 46 
Opening and Closing a Data Set 2.0... ee ee ne 47 
Open/ClosesEOV EMOL <.44.63c494.85 808 9S 4 aoa en Savas Dente eet 49 
OPEN—Prepare a Data Set for Processing ................-.0-04. 51 


Contents Xl 





CLOSE—Terminate Processing of a Data Set .................20.04. 52 ( ‘ 

Volume: Positioning «oi <25 hanes. be Kae Rhos Be ee hee teen oe es 54 ae 
End-of-Volume Processing ......... 0.0. e cece eee eee eee eee 55 

Device: Independence: . iS o yu Raa Ae aS RAO ewe 58 

Chapter 6. Accessing Records in Data Sets .......... 0... cee eee aee 61 

Accessing Data with READ/WRITE ............. 00.00 cece eee eee 61 
READ=Read-a: BIOCK  ¢.4-fhs bo a5 2 EO esa FUE NARS OE EES 62 
WRITE--Write'a BIOCk: 6c id ae beaker hE Oe awa eee eee eS 63 
CHECK—Test Completion of Read or Write Operation ............. 64 
WAIT—Wait for Completion of a Read or Write Operation .......... 64 
Data Event Control Block (DECB) ................. 0.22 65 

Accessing Data with GET/PUT «ww. ne 65 
GET Retneve a-ReCOId: 234 whe ean Bee Ol Stale ae oe Eee See 65 
PUT Write a Record: 23d yee oA ccca eo Oho bee theo eed 66 
PUTX—Whnite an Updated Record ........... 0.0.0... eee eee ee 66 
Parallel Input Processing (QSAM Only) ............. 2.002 eee eens 66 

Shane Data SGtS: 64. aced4 ee cae atatelncaeses sae oo Baste apaueee Baars Sha 69 

Analyzing t/O Rirors. 224.6 ase SN AOS OA OSES 24 eee Go ee 72 
SYNADAF—Perform SYNAD Analysis Function ................. 72 
SYNADRLS—Release SYNADAF Message and Save Areas .......... 73 
ATLAS—Perform Alternate Track Location Assignment ............. 73 

Chapter 7. DCB Exit Routines ....... 0.0.0... cc we cee ee ee eee ene 75 

End-of-Data-Set Exit Routine (EODAD) ....................--20.2. 76 Pa 

Synchronous Error Routine Exit (SYNAD) .....................005. 77 

RI ISIC Ro): teh the Bo ee Wwe oe he eles A eee 80 Ma 7 

Standard: User Label bart. 24 634:400o-4 obs bad Reet hi Pee owe es eas 82 

User Totaling (BSAM and QSAM only) ......... 0.0... eee eee 86 

Data,Control Block Open Exit: os4do54688452 65G0e Hob Hae26 484 455 88 

Open/EOV Nonspecific Tape Volume Mount Exit ................... 88 
Convention for Saving and Restoring General Registers ............. 90 

Open/EOV Volume Security and Verification Exit .................0.4. 90 

- Convention for Saving and Restoring General Registers ............. 93 

QSAM Parallel Input Exit 2... 0... 0. ee ne enn 93 

JPCBE.EM. vince o4-ba55 coud dhe eee tes © a aNeta ts Gane oan ae ae aes 93 

Pnd-Of- Volume EMI 26.00.4405. ba,0-05) 14de-e whe Soe eee eee 94 

Diock Count Ext. esse cutact te hR ee hae ne 8s AoE Os Bee: 94 

Defer Nonstandard Input Trailer Label Exit ......................5. 95 

POP age Xt. 2, c-i0605. 4-2-5 25) harps eta ah Sr ester & A he eA 95 

DCB AbenG Ext. 6 o45-¥o ke eek HRS IE Os EB OS oS 97 
Recovery Requirements: 2.0. ssupeahendh oe ees aw ele d oe paws 101 

Avend Installation’ Exit. 124+ 61 GaGaiw tal ee eS hee mend Sed ae 103 

Chapter 8. Spooling and Scheduling Data Sets) ................-.6. 105 

Chapter 9. Processing a Sequential Data Set ..............0000008 109 

Creating a Sequential Data Set 2... eee eens 109 

Retrieving a Sequential Data Set 2.0... 0.0... ce ee ns 110 

Modifying a Sequential Data Set 2.0... 0... ce ee ee es . AZ 
Updating a Sequential Data Set in Place ................0 000008 112 A 
Extending a Sequential DataSet 2.0.0.0... cece cece eee eee 113 {SY 





Concatenating Sequential Data Sets ........ 0.000. c cee eee eee 113 


Xll MVS/XA Data Administration Guide 














Processing with Chained Scheduling .......... 20... 0.00 eee eee ees 115 


Chained Scheduling Functions for DASD  ...................... 116 
Search Direct for Input Operations .......... 0.00. cee eee eens 117 
Determining the Length of a Record on Input ..................... 117 
Wniting a Short Block When Using the BSAM WRITE Macro ......... 119 
Managing SAM Buller Space: <.2cascdicetaeedes ed ceanbew Cee Ss 119 

Biller-PoolConsiuchOn oucnenes ¥o-cadGoae wey be ee eee kes 120 

Biller COMUiOl, ih<- 344s ae eee ee hee kee ee oa acs oo ows 123 

Buffering Techniques and GET/PUT Processing Modes ............ 128 
Chapter 10. Processing a Partitioned Data Set ................02.8- 131 
Partitioned DataSet Directory. 1408) #6) e285 $e oe 8S See Oe oes 132 
Allocating Space for a Partitioned Data Set ..................000005 135 
Creating a Partitioned Data Set .............. Pee ee ere er are 136 

_ Processing a Member of a Partitioned Data Set .................... 139 

BLDL—Construct a Directory Entry List ................0..2008. 139 

PIND Position to a. Member: sy 465-240 Sew ba shade ee Hee 139 
Retrieving a Member of a Partitioned Data Set ..................2.5. 141 
Modifying a Partitioned Data Set ....... 0.0.00... ee ees 144 

Updating a Member of a Partitioned Data Set ................... 144 

Processing a Partitioned Data Set Residing on MSS ......... Stegner 146 
Concatenating Partitioned Data Sets ........ 0.0.0... cee ee ee eee 146 

Partitioned Concatenalion: 2:4 ¢.cea 6 0 3-545 24 Re Rew EERE G 146 
Reading a BPAM Directory Sequentially ........... 0.0.2... eee eee 147 
Chapter 11. Processing a Direct Data Set .............. 2.22 e eee eee 149 
Direct Data Set Organization ...... 0... 0... ccc ee eee 149 
Creatine a) Direct Data Set. 22325 eusew ev eek 2b Se PU ee Meee aoe bees 150 
Referring to a Record in a Direct Data Set ...................0026. 152 
Adding or Updating Records on a Direct Data Set .................. 154 
Sharimne Direct Data Sets. <u owes ace setae ewe Bie eee 157 
Chapter 12. Processing an Indexed Sequential Data Set .............. 159 
Indexed Sequential Data Set Organization .............0.0 200s eee 159 

PP tee seal ge once Ace wists ee kee ol ato eter SNe Le a ehaits EER a LEO 160 

INGEXYATCES: Sees Gt os ECG ES A eae ee ee Oa ee eee eae 161 

OVETHOW Alicas: cio tain oasis es Wea ee eee S ye es ead 163 
Creating an Indexed Sequential Data Set ...................20000- 163 

Allocating Space for an Indexed Sequential Data Set ............... 166 
Retneving and Updating an Indexed Sequential Data Set ............. 174 

Sequential Retrieval and Update ............ 20... 2... ee ee eee 174 

Direct-Retrieval-and Update: . 2-0-3444 niSai dow i bee edt eee Seeaas 176 
Adding Records to an Indexed Sequential Data Set .................. 182 

Inserting New Records into an Existing Indexed Sequential Data Set ... 182 

Adding New Records to the End of an Indexed Sequential Data Set ... 182 

Maintaining an Indexed Sequential Data Set ..................... 183 

Indexed Sequential Buffer and Work Area Requirements ........... 186 

Controlling an Indexed Sequential Data Set Device ................ 189 
Chapter 13. Generation Data Groups ........... cece eee eceeecces 193 
Absolute Generation and Version Numbers ............... 2000000 ee 194 
Relative: Generation Number <.¢ cerns 6620 oe ot Ab eee DARA eS ESS 194 
Programming Considerations for Multiple Step Jobs ................. 195 


Contents Xlil 








Generation Data Group Naming for aaa. FIPS Version 3 Labels ... 196 


Crealing-a. New Generation: 4.6 .sv-sewe Gree 4442854444 0e 4 So eee CHEE 197 
AMMocaimie aGGNCTAION: 443.4:4.20 Lee had oa hse O80 Enka aes 197 
Passio a Greheraion: shack icine ee es OE Tae ee eo halted 198 
Creating an ISAM Data Set as Part of a Generation Data Group ..... 198 

Retievine-a GeneratiOn: 4.45500 baw aan eee Swale eee waehard gts 199 

Building a Generation Data Group Index .............. 00000000005 199 

Chapter 14. I/O Device Control Macros ............0200 cee eeeee 201 
CNTRL—Control an VO Device .......0..6 0.0 0c cc pew eens eee 201 
PRTOV—Test for Printer Overflow ........... 0.0.00. ee eee 202 
SEL PR Printer Setup. odceie9e denbe woe 8S Sse ae BS eg wc me ere ees 202 
BSP—Backspace a Magnetic Tape or Direct Access Volume ......... 203 
NOTE—Return the Relative Address of a Block ....... tet ete ns aod areas 203 
POINT—Position to a Block 2.0... 0.0.0.0. 000 2c ee 204 
SYNCDEV—Control Data Synchronization ................00000. 204 

Chapter 15. . Protecting. Data.223 3.6046 eh. 4b od eh Ob ee eGR WE 205 

Password Protection for Non-VSAM Data Sets ................0.0.4. 205 

RACF Protection for Non-VSAM Data Sets ................00.004. 206 

Appendix A. Direct Access Labels ............. 2.2.0 cee cece eee eee 209 

Voltiie=LaAbel Group: 2. des ie das See oe BA eo ee eae BES 209 
Initial Volume Label Format .......... 20.0.0... ccc ee eee 210 

Data Set Control Block (DSCB) ..... eee ee a ae ere ee eee ee 211 

Wiser ae! GOURDS: 5.6 64 aoe UG Beets EG e Wen eek ec eee US Se 211 
User Header and Trailer Label Format .....................0000. 212 

Appendix B. Control Characters ......... 0.0... eee eee c cee ees 213 

Machine’ COde= i. 2.05 os éek eed ea bed yee ahaa e ace er anknG oe dateesens 213 

Extended American National Standards Institute Code ............... 215 

Appendix C. Allocating Space on Direct Access Volumes ............. 217 
Estimating Space Requirements ...........0 2 cece cece cc ccseees 218 


Appendix D. ISO/ANSI/FIPS Record Control Word and Segment Control 


WVOIG: 26 ole nat BG aa edt eevee es at ee eet rar acs ee Be ae 223 
Translation of ISO/ANSI/FIPS Record Control Word ............... 223 
Translation of ISO/ANSI/FIPS Segment Control Word .............. 224 
Glossary of Terms and Abbreviations ........... 0.0.2.0. e eee eeees 225 
WINGO 225. 5 rie Saletan atte, St nla ere Ra eo Gata She eh ee eee wee 229 


XIV MV S/XA Data Administration Guide 


ee Bee ye 











Figures 


paws 


Se eS Se ee 








Direct Access Vein Track PORMAtS: ecco ceccds io ace ew aind eile Gaal et 7 
Catalog Stmicture. 2.:254 wiaie tie hageteind dvee eu eee Opes lites Bot 10 
Fixed-Leneth Records: 22444023 42i200neds65d5 if bed ceeds 14 
Fixed-Length Records for ISO/ANSI/FIPS Tapes ............... 17 
Nonspanned, Format-V Records ............... 0.0. e eee eee 18 
Spanned Format-VS Records (Sequential Access Method) ......... 20 
Segiient Control: Codes: <4462 diet ee eck s oS ORR Ge PO REN Sree bt 21 
Spanned Format-V Records for BDAM Data Sets ............... 22 
Nonspanned Format-D Records for ISO/ANSI/FIPS Tapes ........ 24 
Spanned Variable-Length (Format-DS) Records for ISO/ANSI/FIPS 

WADES: Sai ead ta ee ee ae se eons eee aie Git eee eBay oc 26 
Undetined-Length Records | oc.02.2sdi-d ¥ ach-4 5 4 deg Fae eh ede bee 8 oS 28 
Tape Density (DEN) Values ............-.. 0. cece eee eee eee 30 
Data Management Access Methods ..............2.20 0c eeeees 35 
Sources and Sequence of Operations for Completing the Data Control 
BlOCK. 2i:..c020 4s tuceeaeent neo hotedeaeeeo eee tebe aos 42 
Changing a Field in the Data Control Block ................... 46 
Opening Three Data Sets Simultaneously ..................0.. 52 
Record Processed When LEAVE or REREAD Is Specified for CLOSE 
PPE, tues ek, a en eae are ea Be, Seg ee 53 
Closing Three Data Sets cece ate tesa cca eas Bema eee 54 
Parallel Processing of Three Data Sets ............ 2.002000 e eee 68 
JCL, Macro Instructions, and Procedures Required to Share a Data Set 
Using Multiple DCBS: 4.66355 43 643s eed ew i a eee ES 70 
Macro Instructions and Procedures Required to Share a Data Set Using 

a. Single DCB .4.c65a st oa owe od RES oS EER ea 71 
Data Management Exit ROUGHER: cic srsaovecitesha cuceemaccdaun oeuedn td 75 
DCB Exit List Format and Contents ............ 0.0.20 ce eee 80 
Parameter List Passed to User Label Exit Routine ............... 83 
System Response to a User Label Exit Routine Return Code? 254555 84 
IECOENTE Macro Parameter List ............ 00.0.2 eee eee 89 
IECOEVSE Macro Parameter List ....... 20... 0... eee ee ee eee 92 
System Response to Block Count Exit Return Code ............. 95 
Defining an FCB Image fora 3211 2.2.0... . eee ee ee eee 96 
Parameter List Passed to DCB Abend Exit Routine .............. 98 
Conditions for Which Recovery Can Be Attempted .............. 99 
Recovery Work Area: ge ais vebiinlet bie paw ba weve eed aes 102 
Creating a Sequential Data Set—Move Mode, Simple Buffering ..... 110 
Creating a Sequential Data Set—Locate Mode, Simple Buffering .... 111 
Reissuing a READ or GET for Unlike Concatenated Data Sets .... 114 
One Method of Determining the Length of the Record When Using 

BSAM to Read Undefined-Length Records ........,.......00. 118 
Constructing a Buffer Pool from a Static Storage Area ........... 122 


Figures XV 





38. Constructing a Buffer Pool Using GETPOOL and FREEPOOL ... 123 a 


39. Simple Buffering with MACRF=GL and MACRF=PM ........ 126  Y 
40. Simple Buffering with MACRF=GM and MACRF=PM ........ 126 | 
41. Simple Buffering with MACRF=GL and MACRF=PL ......... 127 
42. Simple Buffering with MACRF=GL and MACRF= PM-UPDAT - 
b WAGES. seein oe atee eae eet at ere ek ene ee a ee D 128 
43. Buffering Technique oan GET/PUT Diocese Modes .......... 128 
44. A Partitioned Data Set: oc vousteo sae ed bbe Sw aw eb RA ERE 131 
45. A Partitioned Data Set Directory Block ...............000005. 132 
46. A Partitioned Data Set Directory Entry ...................0.0. 133 
47. Creating One Member of a Partitioned Data Set ............... 136 
48. Creating Members of a Partitioned Data Set Using STOW ........ 138 
49.. BEDUL-list Pomnat setae s jonwadeor eens ee ebacGs 140 
50. Retrieving One Member of a Partitioned Data Set .............. 142 
51. Retrieving Several Members and Subgroups of a Partitioned Data Set 143 
52. Updating a Member of a Partitioned Data Set ................. 145 
do. Creating 4.Direct Data Set. 0036 ov tothe hie ee dek Sun aes 152 
54. Adding Records to a Direct Data Set ..................202005 155 
55. Updating a Direct Data Set .......0. 0.0.0... ee ee ees 156 
56. Indexed Sequential Data Set Organization .................... 160 
57. Format of Track Index Entries ......... 0.0... cee eee ene 162 
58. Creating an Indexed Sequential Data Set ...................5. 165 
59. Requests for Indexed Sequential Data Sets ................005. 168 
60. Sequentially Updating an Indexed Sequential Data Set ........... 175 
61. Directly Updating an Indexed Sequential Data Set .............. 178 
62. Directly Updating an Indexed Sequential Data Set with a 
Variable-Length Records ...... 0... 0. cece eee eee 181 Net 
63. Adding Records to an Indexed Sequential Data Net. oeavas bs esis sense 184 
64. Deleting Records from an Indexed Sequential Data Set .......... 185 
65. Direct Access Labeling ........00. 0. ccc cece eee eee 209 
66. Initial Volume Label ................ ee er nee eee 210 
67. User Header and Trailer Labels ................ 2.0.00. ee ees 211 
68. Direct Access Storage Device Capacities .............0 002008. 219 
69. Direct Access Device Overhead Formulas .................... 220 
70. Translation of ISO/ANSI/FIPS Record Control Word to D/DB 
Record: Descriptor Word) 2 oie 4 eb oe Pe Se wee eee BUS 223 
71. Translation of ISO/ANSI/FIPS Segment Control Word to DS/DBS | 
Segment Descriptor Word ........... 0.0 cece ee eee ee eee 224 





XVi MVS/XA Data Administration Guide 








Chapter 1. Introduction to Data Administration 


Data administration is the process of systematically and effectively organizing, 
identifying, storing, cataloging, and retrieving all the information (including 
programs) that your installation uses. 


Data set storage control, along with an extensive catalog system, makes it 
possible to retrieve data by symbolic name alone, without specifying device types 
and volume serial numbers. In freeing computer personnel from maintaining 
complicated volume serial number inventory lists of stored data and programs, 
the catalog reduces manual intervention and the likelihood of human error. 


A data set 1s a collection of logically related data records that are stored on a 
volume and that may be classified according to installation needs. For example, 
a sales department could classify its data by geographic area, by individual 
salesperson, or by any other logical plan. A user can request data from a direct 
access volume or a tape volume. 

The cataloging system makes it possible to classify successive generations or 
updates of related data. These generations can be given identical names and 
subsequently be referred to relative to the current generation. The system 
automatically maintains a list of the most recent generations. 

Data administration provides: 


e Allocation of space on direct access volumes. 


e Automatic retrieval of cataloged data sets by name alone. 


Overview of Data Set Processing 


Input/output routines in the operating system schedule and control all data 
transfer operations between virtual and auxiliary storage. These routines can: 


e Read data 

e White data 

e Translate data from ISCII/ASCII (International Standard Code for 
Information Interchange and American National Standard Code for 


Information Interchange) to EBCDIC (Extended Binary coe Decimal 
Interchange Code) and the reverse 
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e Block and unblock records 





¢ Overlap reading, writing, and processing operations 
° Read and verify volume and data set labels 

e Write data set labels 

e Position and reposition volumes automatically 

¢ Detect I/O errors and correct them when possible 

@ Provide exits to user-written error and label routines 


_ Data management programs also provide a variety of methods for gaining access 
to a data set. These methods are based on data set organization and data access 
technique. 


You can organize your data sets in one of four ways: 


¢ Sequential: Records are organized in physical rather than logical sequence. 
Given one record, the location of the next record is determined by its 
physical position in the data set. You must use the sequential data set 
organization for all magnetic tape devices, but it is optional on direct access 
devices. Punched cards and printed output must also be sequentially 
organized. 


e Indexed Sequential: Records are arranged in sequence, according to a key 
that is a part of every record, on the tracks of a direct access volume. An 
index or set of indexes maintained by the system gives the location of certain 
principal records. This permits direct and sequential access to any record. 


® Direct: Records within the data set, which must be on a direct access 
volume, may be organized in any manner you choose. All space allocated to 
the data set is available for data records. No space is required for indexes. 
You specify addresses by which records are stored and retneved directly. 


e Partitioned: Independent groups of sequentially organized records, called 
members, are in direct access storage. Each member has a simple name 
stored in a directory that is part of the data set and contains the location of 
the member’s starting point. Partitioned data sets are generally used to store 
programs. As a result, they are often called /ibraries. 


Requests for input/output operations on data sets through macro instructions use 
two techniques: the technique for queued access and the technique for basic 
access. Each technique is identified according to its treatment of buffering and 
synchronization of input and output with processing. The combination of an 
access technique and a given data set organization is called an access method. In 
choosing an access method for a data set, therefore, you must consider not only 
its organization, but also what you need to specify through macros. Also, you 
may choose a data organization according to the access techniques and processing 
capabilities available. | 
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The code generated by the macros for both techniques is optionally reenterable, 
depending on the form in which parameters are expressed. 


Besides the access methods provided by the operating system, an elementary 
access technique called execute channel program (EXCP) 1s also provided. To 
use this technique, you must establish your own system for organizing, storing, 
and retrieving data. The primary advantage of EXCP is the complete flexibility it 
allows you in using the computer directly. 


An important feature of data administration is that much of the detailed 
information needed to store and retrieve data, such as device type, buffer 
processing technique, and length of output records, need not be supplied until the 
job is ready to be executed. This device independence permits changes to those 
specifications to be made without changes in the program. Therefore, you may 
design and test a program without knowing the exact input/output devices that 
will be used when it is executed. 


Device independence is a feature of both the queued and basic access techniques 
for processing sequential data sets. To some extent, you can determine the 
degree of device independence. Many useful device-dependent features are 
available as part of certain macro instructions; achieving device independence 
requires some selectivity in their use. 


Identifying Data Sets 


Any information that is a named, organized collection of logically related records 

can be classified as a data set. The information is not restricted to a specific type, 
purpose, or storage medium. A data set may be, for example, a source program, 

a library of macros, or a file of data records used by a processing program. 


Whenever you indicate that a new data set is to be created and placed on 
auxiliary storage, you (or the operating system) must give the data set a name. 
The data set name identifies a group of records as a data set. All data sets 
recognized by name (referred to without volume identification) and all data sets 
residing on a given volume must be distinguished from one another by unique 
names. To help in this, the system provides a means of qualifying data set 
names. 


A data set name is one simple name or a series of simple names joined together 
so that each represents a level of qualification. For example, the data set name 
DEPT58.SMITH.DATAS3 is composed of three simple names. Proceeding from 
the left, each simple name is a category within which the next simple name is a 
subcategory. The first name is called the high-level qualifier, the last is the 
low-level qualifier. 


Each simple name consists of from 1 to 8 alphameric characters, the first of 
which must be alphabetic. The special character period (.) separates simple 
names from each other. Including all simple names and periods, the length of the 
data set name must not exceed 44 characters. Thus, a maximum of 22 simple 
names can make up a data set name. 
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To permit different executions of a program to process different data sets without ( 





program reassembly, the data set is not referred to by name in the processing Soe 
program. When the program is executed, the data set name and other pertinent 
information (such as unit type and volume serial number) are specified in a job 
control statement called the data definition (DD) statement. To gain access to 
the data set during processing, reference is made to a data control block (DCB) 
associated with the name of the DD statement. Space for a data control block 
that specifies the particular data set to be used is reserved by a DCB macro when 
your program is assembled. 
| 
v 
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Chapter 2. Data Set Storage 


The operating system provides a variety of devices for collecting, storing, and 
distributing data. Despite the variety, the devices have many common 
characteristics. The generic term volume is used to refer to a standard unit of 
auxiliary storage. A volume may be a reel of magnetic tape, a disk pack, or a 
drum. 


Each data set stored on a volume has its name, location, organization, and other 
control information stored in the data set label or volume table of contents (for 
direct access volumes only). Thus, when the name of the data set and the 
volume where it is stored are made known to the operating system, a complete 
description of the data set, including its location on the volume, can be retrieved. 
Then, the data itself can be retrieved, or new data added to the data set. 


Various groups of labels are used to identify magnetic tape and direct access 
volumes, and the data sets they contain. Magnetic tape volumes can have 
standard or nonstandard labels, or they can be unlabeled. Direct access volumes 
must use standard labels. Standard labels include a volume label, a data set label 
for each data set, and optional user labels. 


Keeping track of the volume where a particular data set resides can be a burden 
and a source of error. To alleviate this problem, the system provides for 
automatic cataloging of data sets. The system can retrieve a cataloged data set if 
given only the name of the data set. 


By use of the catalog, collections of data sets related by a common external name 
and the time sequence in which they were cataloged (their generation) can be 
identified; they are called generation data groups. For example, a data set name 
LAB.PAYROLL(0) refers to the most recent data set of the group; 
LAB.PAYROLL(-1) refers to the second most recent data set; and so forth. The 
same data set names can be used repeatedly with no need to keep track of the 
volume serial numbers used. For more information, see “Relative Generation 
Number” on page 194. : 


Direct Access Volumes 


Regardless of organization, data sets created using the operating system can be 
stored on a direct access volume. Each block of data has a distinct location and a 
unique address, making it possible to find any record without extensive searching. 
Thus, records can be stored and retrieved either directly or sequentially. 
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Track Characteristics 


Track Format 





Direct access volumes are used to store executable programs, including the 
operating system itself. Direct access storage (sometimes called DASD storage) is 
also used for data and for temporary working storage. One direct access storage 
volume may be used for many different data sets, and space on it may be 
reallocated and reused. A volume table of contents (VTOC) is used to account 
for each data set and available space on the volume. 


Each direct access volume is identified by a volume label that is stored at track 0 
of cylinder 0. You may specify as many as seven additional labels, located 
following the standard volume label, for further identification. 


The VTOC is a data set consisting of data set control blocks (DSCBs) that 
describe the contents of the direct access volume. The VTOC can contain seven 
kinds of DSCBs, each with a different purpose and a different format number. 
The format 0 DSCB describes an unused (available) record in the VTOC. 
System—Data Administration describes format 1 through format 6 DSCBs and 
their purposes. System—Data Administration also describes the structure of the 
VTOC. 


Each direct access volume is initialized by a utility program before being used on 
the system. The initialization program generates the volume label and builds the 
table of contents. For additional information on direct access labels, see 
Appendix A, “Direct Access Labels” on page 209. 


When a data set is to be stored on a direct access volume, you must supply the 
operating system with the amount of space to be allocated to the data set, 
expressed in blocks, tracks, or cylinders. Space allocation can be independent of 
device type if the request is expressed in blocks. If the request is made in tracks 
or cylinders, you must be aware of such device considerations as cylinder capacity 
and track size. 


Although direct access devices differ in physical appearance, capacity, and speed, 
they are similar in data recording, data checking, data format, and programming. 
The recording surface of each volume is divided into many concentric tracks. 
The number of tracks and their capacity vary with the device. Each device has 
some type of access mechanism, containing read/write heads that transfer data as 
the recording surface rotates past them. 


Information is recorded on all direct access volumes in a standard format. 
Besides device data, each track contains a track descnptor record (capacity record 
or record 0) and data records. 


Figure 1 shows that there are two possible data record formats—count data and 
count key data—only one of which can be used for a particular data set. 
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Figure 1. Direct Access Volume Track Formats 


Track Overflow 


Besides device data, the count area contains 8 bytes that identify the location of 
the record by cylinder, head, and record numbers, its key length (0 if no keys are 
used), and its data length. 


If the records are written with keys, the key area (1 to 255 bytes) contains a 
record key that specifies the data record by part number, account number, 
sequence number, or some other identifier. In some cases, records are written 
with keys so that they can be located quickly. 


If the record overflow feature is available for the direct access device being used, 
you can reduce the amount of unused space on the volume by specifying the 
track overflow option in the DCB parameter of the DD statement, or the DCB 
macro associated with the data set. If the overflow option is used, a block that 
does not fit on the track is partially written on that track and continued on the 
next track. (The track where the record is continued must be physically next and 
must be part of the same extent as the track that holds the first part of the 
record.) 


Each segment (the portion written on one track) of an overflow block has a 
count area. The data length field in the count area specifies the length of that 
segment only. If the block is written with a key, there is only one key area for 
the block. It is written with the first segment. If the track overflow option is not 
used, blocks are not split between tracks. 


Actual and Relative Addressing 


Two types of addresses can be used to store and retrieve data on a direct access 
volume: actual addresses and relative addresses. The only advantage of using 
actual addresses is the elimination of time required to convert from relative to 
actual addresses and vice versa. When sequentially processing a multiple volume 
data set, you can refer only to records of the current volume. 
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Actual Addresses: When the system returns the actual address of a record on a ': 
direct access volume to your program, it is in the form MBBCCHHR, where: ‘ 
M : , 
is a l-byte binary number specifying the relative location of an entry in a 
data extent block (DEB). The DEB is created by the system when the data 
set is opened. Each extent entry describes a set of consecutive tracks 
allocated for the data set. 


BBCCHH 
is three 2-byte binary numbers specifying the cell (bin), cylinder, and head 
number for the record (its track address). The cylinder and head numbers 
are recorded in the count area for each record. 


is a 1-byte binary number specifying the relative block number on the track. 
The block number is also recorded in the count area. 


If you use actual addresses in your program, the data set must be treated as 
unmovable. 


Relative Addresses: ‘Two kinds of relative addresses can be used to refer to 
records in a direct access data set: relative block addresses and relative track 
addresses. 


The relative block address is a 3-byte binary number that shows the position of | : 
the block relative to the first block of the data set. Allocation of noncontiguous See? 
sets of blocks does not affect the number. The first block of a data set always 

has a relative block address of 0. 


The relative track address has the form TTR, where: 


TT 
is a 2-byte binary number specifying the position of the track relative to the 
first track allocated for the data set. The TT for the first track is 0. 
Allocation of noncontiguous sets of tracks does not affect the number. 


is a |-byte binary number specifying the number of the block relative to the 
first block on the track TT. The R value for the first block of data on a 
track is 1. 


Magnetic Tape Volumes 


Because data sets on magnetic tape devices must be organized sequentially, the 

operating system does not require space allocation procedures comparable to that 

for direct access devices. When a new data set is to be placed on a magnetic tape ~ : 
volume, you must specify the data set sequence number if it is not the first data 
set on the reel. The operating system positions a volume with IBM standard 
labels, ISO/ANSI/FIPS labels, or no labels so that the data set can be read or 
written. If the data set has nonstandard labels, you must provide for volume 
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positioning in your nonstandard label processing routines. All data sets stored on 
a given magnetic tape volume must be recorded in the same density. 





When a data set is to be stored on an unlabeled tape volume and you have not 
specified a volume serial number, the system assigns a serial number to that 
volume and to any additional volumes required for the data set. Each such 
volume is assigned a serial number of the form Lxxxyy, where xxx is the data set 
sequence number, and yy is the volume sequence number for the data set. If you 
specify volume serial numbers for unlabeled volumes where a data set is to be 
stored, the system assigns volume serial numbers to any additional volumes 
required. If data sets residing on unlabeled volumes are to be cataloged or 
passed, you should specify the volume serial numbers for the volumes required. 
This ensures that data sets residing on different volumes are not cataloged or 
passed under identical volume serial numbers. Retrieving such data sets can give 
unpredictable errors. 








Each data set and data set label group must be followed by a tapemark. 
Tapemarks cannot exist within a data set. When the operating system creates a 
tape with standard labels or no labels, all tapemarks are automatically written. 
Two tapemarks follow the last trailer label group on a standard-label volume. 
On an unlabeled volume, the two tapemarks appear after the last data set. 


When the operating system creates data sets with nonstandard labels, no 
tapemarks are written. If you want the operating system to retrieve a data set, 
you must supply the tapemarks in your routine that creates the nonstandard-label 
volume. Otherwise, tapemarks are not required after nonstandard labels, because 
positioning of the tape volumes must be handled by installation routines. 


For more information about magnetic tape volume labels, see Magnetic Tape 
Labels and File Structure. 


The data on magnetic tape volumes can be in either EBCDIC or ISCII/ASCI. 
ISCIH/ASCII 1s a 7-bit code consisting of 128 characters. It permits data on 
magnetic tape to be transferred from one computer to another, even though the 
two computers may be products of different manufacturers. 


Data management support of ISCII/ASCII and of the International Organization 
for Standardization (ISO), American National Standards Institute (ANSI), and 
Federal Information Processing Standard (FIPS) tape labels is such that data 
management can translate records on input tapes in ISCII/ASCII into EBCDIC 
for internal processing and translate the EBCDIC into ISCII/ASCII for output. 
Records on such input tapes may be sorted into ISCII/ASCII collating sequence. 
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Cataloging Data Sets f 


The operating system has a catalog structure consisting of a master catalog, user 
catalogs, and, optionally, OS CVOLs. Figure 2 shows the catalog structure. 


Master Catalog 


| USERID 


SYSCTLG.V 111111! 









CAT je User Catalog Control Volume 
: DataSet | 
Data Set A i ., Patame re GiB. USERID.B 
7 Data Set A 


Data Set Data Set 
UCAT-B | USERID.B 





1 11111 1s the volume serial of the OS CVOL. 


Figure 2. Catalog Structure No 


There is one master catalog on each system. It is required and contains entries 
for system data sets. It is also the VSAM or integrated catalog facility master 
catalog and does not have to be on the system residence volume. The master 
catalog contains a pointer to each user catalog. Both VSAM and non-VSAM 
data sets can be cataloged in a user catalog. 


Non-VSAM data sets can be cataloged on OS CVOLs (SYSCTLG data sets). 
The master catalog contains a pointer to each OS CVOL. Data sets can be 
cataloged, uncataloged, or recataloged. (For more information on using OS 
CVOLs, see Catalog Administration Guide.) If a data set is not cataloged in the 
master catalog, the first name of a qualified data set name indicates the user 
catalog or OS CVOL in which it is cataloged. A user catalog can also be 
connected to the system as a job catalog or a step catalog. 


Permanent Mass Storage System (MSS) data sets should be cataloged to allow 
efficient use of the mass storage volume control (MSVC) functions. For 
information on MSVC, see OS/VS Mass Storage System (MSS) Services: 
General Information. 
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Entering a Data Set Name in the Catalog 


The data set name of a non-VSAM data set can be entered in a master or user 
catalog through (1) job control language (DISP parameter), (2) access method 
services (DEFINE command), or (3) catalog management macro instructions 
(CATALOG and CAMLST). A non-VSAM data set name can be entered in an 
OS CVOL through JCL or the catalog management macros. VSAM data sets 
can only be cataloged by using access method services. 


Access method services is also used to establish aliases for data set names and to 
connect user catalogs and OS CVOLs to the master catalog. For information on 
how to use the access method services commands, see Access Method Services 
Reference. For information on how to use the catalog management macro 
instructions, see Catalog Administration Guide and System Data Administration. 


Data set names cannot be cataloged in an OS CVOL if a name 1s already 
cataloged whose levels match the highest or higher levels of the specified name. 
For example, the qualified name A.B.C.D cannot be cataloged if the name A.B 
or A.B.C is already cataloged, but the name A.B.C.D can be cataloged if AB.C 
or A.B.C.E is cataloged. This restriction is not true for data sets cataloged in an 
integrated catalog facility or VSAM catalog. 
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Chapter 3. Record Formats 


The record is the basic unit of information used by a processing program and can 
be anything from a single character to a mass of information collected by a 
particular business transaction, or measurements recorded at a given point in an 
experrment. A collection of logically related records makes up a data set. Most 
data processing consists of reading, manipulating, and writing individual records. 


Blocking is the process of grouping records before they are written on a volume. 
A block consists of one or more logical records written between consecutive 
interrecord gaps (IRGs). Blocking conserves storage space on a volume by 
reducing the number of IRGs in the data set and increases processing efficiency 
by reducing the number of input/output operations required to process the data 
set. 


7 Records are stored in one of four formats: fixed-length (format-F), variable-length 
{ : for data in EBCDIC (format-V) or for data to be translated to or from 
ISCII/ASCII (format-D), or undefined-length (format-U). 


Before selecting a record format, you should consider: 


e The data type (for example, EBCDIC) your program will receive and the 
type of output it will produce 


e The input/output devices that will contain the data set 
e The access method you will use to read and wnite the records 


You identify your record format selection in the data control block using the 
options in the DCB macro, the DD statement, or the data set label. 


ISO/ANSI/FIPS tape records are written in format-F, format-D, format-S or 
format-U with the restrictions noted under “Fixed-Length Records, 
ISO/ANSI/FIPS Tapes” .on page 15, “ISO/ANSI/FIPS Vanable-Length 
Records—Format D” on page 23, and “Undefined-Length Records” on page 27. 


Note: Data can only be in format-U for ISO/ANSI Version | tapes (ISO 
1001-1969 and ANSI X3.27-1969). 


When data management reads records from ISO/ANSI/FIPS tapes, it translates 
the records into EBCDIC. When data management wnites records onto 
ISO/ANSI/FIPS tapes, it translates the records into ISCII/ASCII characters. 
Because you use input records after they are translated and because output 
records are translated when you ask data management to wnite them, you work 
only with EBCDIC. 
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Note: Translation routines supplied by the system will convert to ASCII 7-bit _ 
code, as explained in Magnetic Tape Labels and File Structure. When the Nae 
character to be translated contains a bit in the high order position, the 7-bit 

translation does not produce an equivalent character. Instead, it produces a 

substitute character to note the loss in translation. This means, for example, that 

random binary data (such as a dump) cannot be recorded in ISO/ANSI/FIPS 

7-bit code. 


Fixed-Length Records 


The size of fixed-length (format-F) records, shown in Figure 3, is constant for all 
records in the data set. The number of records within a block is constant for 
every block in the data set, unless the data set contains truncated (short) blocks. 
If the data set contains unblocked format-F records, one record constitutes one 


block. 


The system automatically performs physical length checking (except for card 
readers) on blocked or unblocked format-F records. Allowances are made for 
truncated blocks. 


Format-F records are shown in Figure 3. The optional control character (a), 
used for stacker selection or carriage control, may be included in each record to 
be printed or punched. 


Block Block 


°.-- --SITwaoa24#Ov~vNT™“"“"VCVVKO*TVTVT——” 


Blocked 
Records 





__ Optional Control 
‘ Character-1 Byte / 


\ / 


Block Block Block 


\ / 
\ / eee een 
Unblocked Record A | Record B Record C Record D 
Records 


Figure 3. Fixed-Length Records 


Fixed-Length Records, Standard Format 


14 


During creation of a sequential data set (to be processed by BSAM or QSAM) 
with fixed-length records, the RECFM subparameter of the DCB macro 
instruction may specify a standard format (RECFM=FS or FBS). A 
standard-format data set must conform to the following specifications: 
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@ All records in the data set are format-F records. 


© No block except the last block 1s truncated. (With BSAM, you must ensure 
that this specification 1s met.) 


e Every track except the last contains the same number of blocks. 


e Every track except the last is filled to capacity as determined by the track 
capacity formula established for the device. (These formulas are presented in 
Appendix C, “Allocating Space on Direct Access Volumes” on page 217.) 


e The data set organization is physical sequential. A member of a partitioned 
data set cannot be specified. 


A sequential data set with fixed-length records having a standard format can be 
read more efficiently than a data set that doesn’t specify a standard format. This 
efficiency 1s possible because the system is able to determine the address of each 
record to be read, because each track contains the same number of blocks. 


You should never extend a standard-format data set (by coding DISP = MOD) if 
the last block is truncated, because the extension will cause the data set to 
contain a truncated block that isn’t the last block. Reading an extended data set 
with this condition will result in a premature end of data condition when the 
truncated block is read, giving the appearance that the blocks following this 
truncated block do not exist. This type of data set on magnetic tape should not 
be read backward, because the data set would begin with a truncated block. 
Consequently, you probably won’t want to use this type of data set with 
magnetic tape. If you use one of the basic access techniques with this type of 
data set, you should not use the track overflow feature. 


Standard format should not be used to read records from a data set that was 
created using a RECFM other than standard, because other record formats may 
not create the precise format required by standard. 


If at any time the characteristics of your data set are altered from the 
specifications described above, the data set should no longer be processed with 
the standard format specification. 


Fixed-Length Records, ISO/ANSI/FIPS Tapes 


For ISO/ANSI/ FIPS tapes, format-F records are the same as described above, 
with three exceptions: 


¢ Control characters, if present, must be ISO/ANSI/FIPS control characters. . 
For more information about control characters, see Appendix B, “Control 
Characters” on page 213. 7 


e Record blocks can contain block prefixes. 
The block prefix can vary from 0 to 99 bytes, but the length must be 
constant for the data set being processed. For blocked records, the block 


prefix precedes the first logical record. For unblocked records, the block 
prefix precedes each logical record. | 
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Using QSAM and BSAM to read records with block prefixes requires that 
you specify the BUFOFF operand in the DCB. When using QSAM, you do 
not have access to the block prefix on input. When using BSAM, you must 
account for the block prefix on both input and output. When using either 
QSAM or BSAM, you must account for the length of the block prefix in the 
BLKSIZE and BUFL operands of the DCB. 


When using QSAM to output DB or DBS records and BUFOFF = 0 is 
specified, the value of the BUFL operand, if specified, must be increased by 
4. If BUFL is not specified, then the BLKSIZE operand must be increased 
by 4. This allows for a 4-byte QSAM internal processing area to be included 
when the system acquires the buffers. These 4 bytes will not become part of 
the user’s block. 


When you use BSAM on output records, the operating system does not 
recognize a block prefix. Therefore, if you want a block prefix, it must be 
part of your record. Note that you cannot include block prefixes in QSAM 
output records. 


The block prefix, as for all the data records for ISO/ANSI/FIPS tapes, can 
only contain EBCDIC characters that correspond to the 128, seven-bit 
ASCII characters. Thus, you must avoid using data types such as binary, 
packed decimal, and floating point that cannot always be translated into 
ISCII/ASCII. (See the Note in Chapter 3, “Record Formats” on page 13.) 


Figure 4 on page 17 shows the format of fixed-length records for 
ISO/ANSI/FIPS tapes and where control characters and block prefixes are 
positioned if they exist. 


¢ The GET routine tests each record (except the first) for all circumflex 
characters (X‘5E’). If a record completely filled with circumflex characters is 
detected, the end-of-block (EOB) routine is called to get the next block. A 
fixed-length record must not consist of only circumflex characters. This 
restriction 1s necessary because circumflex characters are used to pad out a 
block of records when fewer than the maximum number of records are 
included in a block, and the block is not truncated. 
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Figure 4. Fixed-Length Records for ISO/ANSI/FIPS Tapes 





Variable-Length Records 


The variable-length record formats are format-V and format-D. They can also be 
spanned (format-VS or -DS), blocked (format-VB or -DB), or both (format-VBS 
and -DBS). Format-D, -DS, and -DBS records are used for ISO/ANSI/FIPS 
tape data sets. Figure 5 on page 18 shows blocked and unblocked 
variable-length (format-V) records without spanning. 
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Figure 5. Nonspanned, Format-V Records 


Variable-Length Records—Format-V 


Format V provides for variable-length records and variable-length record 
segments, each of which describes its own characteristics, and for variable-length 
blocks of such records or record segments. Except when variable-length track 
overflow records are specified for volumes on devices with the rotational position 
sensing feature, the control program performs length checking of the block and 
uses the record or segment length information in blocking and unblocking. The 
first 4 bytes of each record, record segment, or block make up a descriptor word 
containing control information. You must allow for these additional 4 bytes in 
both your input and output buffers. 


Block Descriptor Word: A variable-length block consists of a block descriptor 
word (BDW) followed by one or more logical records or record segments. The 
block descriptor word is a 4-byte field that describes the block. The first 2 bytes 
specify the block length LL—4 bytes for the BDW plus the total length of all 
records or segments within the block. This length can be from 8 to 32760 bytes 
or, when you are using WRITE with tape, from 18 to 32760. The third and 
fourth bytes are reserved for possible future system use and must be 0. If the 
system does your blocking—that is, when you use the queued access 
technique—the operating system automatically provides the BDW when it writes 
the data set. If you do your own blocking—that is, when you use the basic access 
technique—you must supply the BDW. | 
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Record Descriptor Word: A variable-length logical record consists of a record 
descriptor word (RDW) followed by the data. The record descriptor word is a 
4-byte field describing the record. The first 2 bytes contain the length LL of the 
logical record (including the 4-byte RDW). The length can be from 4 to 32756. 
All bits of the third and fourth bytes must be 0, because other values are used for 
spanned records. For output, you must provide the RDW except in data mode 
for spanned records (described under “Buffer Control” on page 123). For output 
in data mode, you must provide the total data length in the physical record length 
field (DCBPRECL) of the DCB. For input, the operating system provides the 
RDW except in data mode. In data mode, the system passes the record length to 
your program in the logical record length field (DCBLRECL) of the DCB. The 
optional control character (a) may be specified as the fifth byte of each record 
and must be followed by at least one byte of data (the length in the RDW, in this 
case, would be 6). The first byte of data is a table reference character if 
OPTCD=J has been specified. The RDW, the optional control character, and 
the optional table reference character are not punched or printed. 


Spanned Format-VS Records (Sequential Access Method) 


Figure 6 on page 20 shows how the spanning feature of the queued and basic 
sequential access methods lets you create and process variable-length logical 
records that are larger than one physical block and/or to pack blocks with 
variable-length records by splitting the records into segments so that they can be 
written into more than one block. 


When spanning 1s specified for blocked records, the system tries to fill all blocks. 
For unblocked records, a record larger than block size is split and written in two 
or more blocks, each block containing only one record or record segment. Thus 
the block size may be set to the one that is best for a given device or processing 
situation. It is not restricted by the maximum record length of a data set. A 
record may, therefore, span several blocks, and may even span volumes. Note 
that a logical record spanning three or more volumes cannot be processed in 
update mode (described under “Buffer Control” on page 123) by QSAM. For 
blocked records, a block can contain a combination of records and record 
segments, but not multiple segments of the same record. When records are added 
to or deleted from a data set, or when the data set is processed again with 
different block size or record size parameters, the record segmenting will change. 
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Considerations for Processing Spanned Record Data Sets 


When spanned records span volumes, reading errors may occur when using 
QSAM if a volume that begins with a middle or last segment is mounted first or 
if an FEOV macro instruction is issued followed by another GET. QSAM 
cannot begin reading from the middle of the record. The errors include duplicate 
records, program checks in the user’s program, and invalid input from the 
spanned record data set. 


When QSAM opens a spanned record data set in UPDAT mode, it uses logical 
record interface (LRI) to assemble all segments of the spanned record into a 
single, logical input record and to disassemble a single logical record into multiple 
segments for output data blocks. A record area must be provided by using the 
BUILDRCD macro instruction or by specifying BFTEK = A in the DCB. 


Note: When you specify BFTEK = A, the Open routine provides a record area 
equal to the LRECL specification, which should be the maximum length in 
bytes. (An LRECL = 0 is invalid.) 


If you issue the FEOV macro when reading a data set that spans volumes, or if a 
spanned multivolume data set is opened to other than the first volume, make sure 
that each volume begins with the first (or only) segment of a logical record. 

Input routines cannot begin reading in the middle of a logical record. 
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Segment Descriptor Word: Each record segment consists of a segment descriptor 
word (SDW) followed by the data. The segment descriptor word, similar to the 
record descriptor word, is a 4-byte field that describes the segment. The first 2 
bytes contain the length LL of the segment, including the 4-byte SDW. The 
length can be from 5 to 32756 bytes or, when you are using WRITE with tape, 
from 18 to 32756 bytes. The third byte of the SDW contains the segment control 
code that specifies the relative position of the segment in the logical record. The 
segment control code is in the rightmost 2 bits of the byte. The segment control 
codes are shown in Figure 7. The remaining bits of the third byte and all of the 
fourth byte are reserved for possible future system use and must be 0. 


Binary 

Code _ Relative Position of Segment 

00 Complete logical record 

01 First segment of a multisegment record 

10 Last segment of a multisegment record 

1] Segment of a multisegment record other than the first or last segment 


Figure 7. Segment Control Codes 


The SDW for the first segment replaces the RDW for the record after the record 
has been segmented. You or the operating system can build the SDW, depending 
on which access method is used. In the basic sequential access method, you 

must create and interpret the spanned records yourself. In the queued sequential 
access method move mode, complete logical records, including the RDW, are 
processed in your work area. GET consolidates segments into logical records and > 
creates the RDW. PUT forms segments as required and creates the SDW for 
each segment. Data mode is similar to move mode, but allows reference only to 
the data portion of the logical record (that is, to one segment) in your work area. 
The logical record length is passed to you through the DCBLRECL field of the 
data control block. In locate mode, both GET and PUT process one segment at 
atime. However, in locate mode, if you provide your own record area using the 
BUILDRCD macro or if you ask the system to provide a record area by 
specifying BFTEK =A, then GET, PUT, and PUTX process one logical record 
at atime. (BFTEK=A or the BUILDRCD macro cannot be specified when 
logical records exceed 32760 bytes. To process logical records that exceed 32760 
bytes, you must use locate mode and specify LRECL= X in your DCB macro.) 


A logical record spanning three or more volumes cannot be processed when the 
data set is opened for update. 


When unit record devices are used with spanned records, the system assumes that 
unblocked records are being processed and the block size must be equivalent to 


the length of one print line or one card. Records that span blocks are written 
one segment at a time. 


Note: Spanned variable-length records cannot be specified for a SYSIN data set. 
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Null Segments | 7 — 


A 1 in bit position 0 of the SDW indicates a null segment. A null segment 
means that there are no more segments in the block. Bits 1 to 7 of the SDW and 
the remainder of the block must be binary zeros. A null segment is not an 
end-of-logical-record delimiter. (You do not have to be concerned about null 
segments unless you have created a data set using null segments.) 


Spanned Variable-Length Records (Basic Direct Access Method) 


The spanning feature of the basic direct access method (BDAM) lets you create 
and process variable-length unblocked logical records that span tracks. The 
feature also lets you pack tracks with variable-length records by splitting the 
records into segments. Figure 8 shows how these segments can then be written 
onto more than one track. 
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Figure 8. Spanned Format-V Records for BDAM Data Sets 


When you specify spanned, unblocked record format for the basic direct access 
method and when a complete logical record cannot fit on the track, the system 
tries to fill the track with a record segment. Thus the maximum record length of 
a data set is not restricted by track capacity. Furthermore, segmenting records 


mA 


22  MVS/XA Data Administration Guide 




















allows a record to span several tracks, with each segment of the record on a 
different track. However, because the system does not allow a record to span 
volumes, all segments of a logical record in a direct data set are on the same 
volume. 


ISO/ANSI/FIPS Vanriable-Length Records—Format D 


For ISO/ANSI/FIPS tapes, nonspanned variable-length records are format-D 
records. ISO/ANSI/FIPS records are the same as format-V records, with the 
following exceptions: 


Block prefix—A record block can contain a block prefix. To specify a block 
prefix, code the BUFOFF operand in the DCB macro. The block prefix can 
vary in length from 0 to 99 bytes but its length must remain constant for all 
records in the data set being processed. For blocked records, the block prefix 
precedes the RDW for first or only logical record in each block. For 
unblocked records, the block prefix precedes the RDW for each logical 
record. 


To specify that the block prefix is to be treated as a BDW by data 


‘management for format-D or -DS records on output, code BUFOFF = L as 


a DCB operand. Your block prefix must be 4 bytes long, and it must 
contain the length of the block, including the block prefix. The maximum 
length of a format-D or -DS, BUFOFF = L block is 9999, because the length 
(stated in binary by the user) is translated to a 4-byte ASCII character 
decimal field on the ISO/ANSI/FIPS tape when the block is written. It is 
converted back to a 2-byte length field in binary followed by two bytes of 
zeros when the block is read. If you use QSAM to write records, data 
management fills in the block prefix for you. If you use BSAM to write 
records, you must fill in the block prefix yourself. If you are using chained 
scheduling to read blocked DB or DBS records, you cannot code 
BUFOFFE = absolute expression in the DCB. Instead, BUFOFF = L is 
required, because the access method needs binary RDWs and valid block 
lengths to unblock the records. 


When you use QSAM, you cannot read the block prefix into your record 
area on input. When using BSAM, you must account for the block prefix on 
both input and output. When using either QSAM or BSAM, you must 
account for the length of the block prefix in the BLKSIZE and BUFL 
operands. 


When you use BSAM on output records, the operating system does not 
recognize the block prefix. Therefore, if you want a block prefix, it must be 
part of your record. | 


The block prefix can only contain EBCDIC characters that correspond to the 
128, seven-bit ASCII characters. Thus, you must avoid using data types, such 
as binary, packed decimal, and floating point, that cannot always be | 
translated into ISCII/ASCII. (See the Note in Chapter 3, “Record 

Formats” on page 13.) For DB and DBS records, the only tyme the block 
prefix can contain binary data is when you have coded BUFOFF = L, which 
tells data management that the prefix is a BDW. Unlike the block prefix, the 
RDW must always be in piety: 
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e Block size—Version 3 tapes have a maximum block size of 2048. This limit 
may be overridden by a label validation installation exit. 


If you create variable-length blocks that are shorter than 18 bytes, data 
management pads each one to 18 bytes when the blocks are written onto an 
ISO/ANSI/FIPS tape. The padding character used is the ISCII/ASCII 
circumflex character. | 


¢ Control characters—Control characters, if present, must be ISO/ANSI control 
characters. For more information about control characters, see 
Appendix B, “Control Characters” on page 213. 


Figure 9 shows the format of nonspanned variable-length records for 
ISO/ANSI/FIPS tapes, where the record descriptor word (RDW) 1s located, and 


where block prefixes and control characters must be placed when they are used. 
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Note: Block prefixes on output records must be 4-bytes long. 


Figure 9. Nonspanned Format-D Records for ISO/ANSI/FIPS Tapes 






ISO/ANSI/FIPS Variable-Length Spanned Records—Format-DS or Format-DBS 


For ISO/ANSI/FIPS tapes, variable-length spanned records must be specified in 
the DCB RECFM parameter as DCB RECFM=DS or DBS. Format-DS and 
-DBS records are similar to format-VS or -VBS records with the following - 
exceptions: 


e Segment descriptor word (SDW )—There is an additional byte preceding each 
SDW for DS/DBS records. This additional byte is required for conversion of 
the SDW from IBM to ISO/ANSI/FIPS format, because the ISO/ANSI 
SDW (called a segment control word) 1s five bytes long. Otherwise, the SDW 
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( 7 for DS/DBS records is the same as the SDW for VS/VBS records. The 
k. SDW LL count excludes the additional byte. (See “Processing Considerations 
for DS and DBS Records” on page 25.) 


¢ Extended logical record interface ( XLRI )—DS/DBS records may be 
processed using XLRI. (See “Processing Considerations for DS and DBS 
Records.’’) 


e The exceptions previously noted (“ISO/ANSI/FIPS Variable-Length 
Records—Format D” on page 23) for format-D records still apply. 


Figure 10 on page 26 shows what spanned variable-length records for 
ISO/ANSI/FIPS tapes look like when you are using IBM access methods. The 
figure shows the segment descriptor word (SDW), where the record descriptor 
word (RDW) 1s located, and where block prefixes must be placed when they are 
used. If you are not using IBM access methods, see 

Appendix D, “ISO/ANSI/FIPS Record Control Word and Segment Control 
Word” on page 223, for a description of ISO/ANSI/FIPS record control words 
and segment control words. 


Processing Considerations for DS and DBS Records 


When using QSAM, the same application used to process VS/VBS tape files can 
be used to process DS/DBS tape files. However, you must ensure that 
7 ISO/ANSI/FIPS requirements such as block size limitation, tape device, and 
( ; restriction to EBCDIC characters that correspond to the 128, seven-bit ASCII 
characters are met. The SCW/SDW conversion and buffer positioning is handled 
by the GET/PUT routines. 


When using BSAM to process a DS/DBS tape file, you must allow for an 
additional byte at the beginning of each SDW. The SDW LL must exclude the 
additional byte. On input, you must ignore the unused byte preceding each SDW. 
On output, you must allocate the additional byte for each SDW. 


SDW Conversion: Sequential access method end-of-block (EOB) routines 
perform conversion between ISO/ANSI/FIPS segment control word (SCW) 
format and IBM segment descriptor word (SDW) format for both QSAM and 
BSAM processing. On output, the binary SDW LL value (provided by you — 
when using BSAM and by the access method when using QSAM), is increased 
by 1 for the extra byte and converted to four ISO/ANSI/FIPS numeric 
characters. Because the binary SDW LL value will result in four numeric 
characters, the binary value must not be greater than 9998. The fifth character is 
used to designate which segment type (complete logical record, first segment, last 
segment, or intermediate segment) is being processed. 


On input, the four numeric characters designating the segment length are 
converted to two binary SDW LL bytes and decreased by one for the unused 
byte. The ISO/ANSI/FIPS segment control character maps to the DS/DBS 
SDW control flags. This conversion leaves an unused byte at the beginning of 
each SDW. It is set to X’00’. For more detail on this process, see 

Appendix D, “ISO/ANSI/FIPS Record Control Word and Segment Control 
Word” on page 223. 
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Figure 10. Spanned Variable-Length (Format-DS) Records for ISO/ANSI/FIPS Tapes 
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XLRI Mode: ‘The extended logical record interface (XLRI) may be used with 
DS/DBS files to communicate LRECL values over 32760. (XLRI is supported 
only in QSAM locate mode for ISO/ANSI/FIPS tapes.) XLRI should be used 
for any case where the logical record will exceed 32760 bytes. Using the 
LRECL= X for ISO/ANSI/FIPS causes an 013-DC abend. 


To use XLRI, specify LRECL=0K or LRECL=nkK in the DCB macro. 
Specifying DCBLRECL with the K suffix sets the DCBBFTK bit that indicates 
that LRECL is coded in K units and that the DCB is to be processed in XLRI 
mode. 


LRECL= OK in the DCB macro specifies that the LRECL value will come from 
the file label or JCL. When LRECL is from the label, the file must be opened as 
an input file. The label (HDR2) value for LRECL will be converted to kilobytes 
and rounded up when XLRI is in effect. When the ISO/ANSI/FIPS label value 
for LRECL is 00000 to show that the maximum record length may be greater 
than 99999, the LRECL=nK must be used in the JCL or in the DCB to specify 
the maximum record length. 


The LRECL from JCL can be expressed in absolute form or with the K 
notation. Absolute values, permissible only from 5 to 32760, will be converted to 
kilobytes by rounding up to an integral multiple of 1024 when the DCB is for 
XLRI. 


To show the record area size in the DD statement, code DCB = LRECL=nkK. 
The value nK may range from 1K to 16383K (expressed in 1024-byte multiples). 
However, depending on the buffer space available, the value you can specify in 
most systems will be much smaller than 16383K bytes. This value is used to 
determine the size of the record area required to contain the largest logical record 
of the spanned format file. 


When using XLRI, the exact LRECL size is communicated in the three 
low-order bytes of the RDW in the record area. This special RDW format exists 
only in the record area to communicate the length of the logical record (including 
the 4-byte RDW) to be written or read. (See the XLRI format of the RDW in 
Figure 10 on page 26.) DCB LRECL shows the 1024-multiple size of the 
record area (rounded up to the next nearest kilobyte). The normal DS/DBS 
SDW format is used at all other times before conversion. 


Undefined-Length Records 


Format-U permits processing of records that do not conform to the F or V 
format. Figure 11 on page 28 shows how each block 1s treated as a record; 
therefore, any unblocking that is required must be performed by your program. 
The optional control character may te used 1n the first byte of each record. 
Because the system does not do length checking on format-U records, your 
program may be designed to read less than a complete block into virtual storage. 
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Figure 11. Undefined-Length Records 


For format-U records, the user must specify the record length when issuing the 
WRITE, PUT, or PUTX macro instruction. No length checking is performed 
by the system, so no error indication will be given if the specified length does not 
match the buffer size or physical record size. 


In update mode, you must issue a GET or READ macro before you issue a 
PUTX or WRITE macro to a data set on a direct access device. If you change 
the record length when you issue the PUTX or WRITE macro, the record will 
be padded with zeros or truncated to match the length of the record received 
when the GET or READ macro was issued. No error indication will be given. 


For Version 3 ISO/ANSI/FIPS tapes, format-U records are not supported. An 
attempt to process a format-U record from a Version 3 tape will result in entering 
the label validation installation exit. 


ISO/ANSI Version 1 (ISO 1001-1969 and ANSI X3.27-1969) tapes containing 
format-U records can be used for input only. These records are the same as the. 
format-U records described above, except the control characters must be 
ISO/ANSI control characters, and block prefixes can be used. 


Record Format—Device Type Considerations 


Before executing your program, you must supply the operating system with the 
record format (RECFM) and device-dependent information in a DCB macro 
instruction, a DD statement, or a data set label. The DCB subparameters for the 
DD statement differ slightly from those described here. A complete description 
of the DD statement and a glossary of DCB subparameters are contained in /CL. 


The record format (RECFM) parameter of the DCB macro specifies the 
characteristics of the records in the data set as fixed-length (RECFM= FP), 


variable-length (RECFM = V or D), variable-spanned (RECFM = DS or -VS), or 


undefined-length (RECFM= U). All record formats except U can be blocked. 
Fixed-length blocked records (RECFM = FB) can be specified as standard 
(RECFM= FBS), meaning that there are no truncated (short) blocks or unfilled 
tracks within the data set, with the possible exception of the last block or track. 
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Data sets with a fixed-length, standard format are described under “Fixed-Length 
Records, Standard Format” on page 14. 


As an optional feature, a control character can be contained in each record. This 
control character will be recognized and processed if the data set is printed or 
punched. The control characters are transmitted on both tapes and direct access 
volumes. The presence of a control character is indicated by M or A in the 
RECFM field of the data control block. M denotes machine code; A denotes 
American National Standards Institute (ANSI) code. If either M or A is 
specified, the character must be present in every record; the printer space 
(PRTSP) or stacker select (STACK) field of the DCB 1s ignored. The optional 
control character must be in the first byte of format-F and format-U records and 
in the fifth byte of format-V records and format-D records where BUFOFF = L. 
Control character codes are listed in Appendix B, “Control Characters” on 

page 213. The device-dependent (DEVD) parameter of the DCB macro specifies 
the type of device where the data set’s volume resides: 


TA magnetic tape 

PR printer 

PC card punch 

RD card reader 

DA _ direct access device or Mass Storage System (MSS) virtual volumes 


Note: Because the DEVD option is required only for the DCB macro 


expansion, you are guaranteed the maximum device flexibility by letting it default 


to DEVD= DA. 


Format-F, -V, -D, and -U records are acceptable for magnetic tape. Format-V 
records are not acceptable on 7-track tape if the data conversion feature is not 
available. ASCII records are not acceptable on 7-track tape. 


When you create a tape data set with variable-length record format-V or -D, the 
control program pads any data block shorter than 18 bytes. For format-V 
records, it pads to the nght with binary zeros so that the data block length equals 
18 bytes. For format-D (ASCID) records, the padding consists of ASCII 
circumflex characters, which are equivalent to X’5E’s. 


Note that there is no minimum requirement for block size. However, in 
nonreturn-to-zero-inverted mode, if a data check occurs on a magnetic tape 
device, any record shorter than 12 bytes in a read operation will be treated as a 
noise record and lost. No check for noise will be made unless a data check 
occurs. 


Figure 12 on page 30 shows how the tape density (DEN) specifies the recording 


density in bits per inch per track. When DEN is not specified, the highest density 
capable by the unit will be used. 
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Recording Density ~ 
DEN 7-Track Tape 9-Track Tape 18-Track Tape 
l 556 (NRZI) N/A N/A 
Z 800 (NRZIJ) 800 (NRZI)! N/A 
3 N/A 1600 (PE)? N/A 
4 N/A 6250 (GCR) N/A 
Notes: 
1 NRZI 1s for nonreturn-to-zero-inverted mode. 
2 PE 1s for phase encoded mode. 
3. GCR is for group coded recording mode. 
Figure 12. Tape Density (DEN) Values 
The track recording technique (TRTCH) for 7-track tape can be specified as: 
C 
Data conversion is to be used. Data conversion makes it possible to write 
8 binary bits of data on 7 tracks. Otherwise, only 6 bits of an 8-bit byte are 
recorded. The length field of format-V records contains binary data and is a 
not recorded correctly without data conversion. oe 
E 
Even parity is to be used; if E is omitted, odd parity is assumed. 
T 


BCDIC to EBCDIC translation is required. 


Card Reader and Punch 


Format-F and -U records are acceptable to both the reader and the punch; 
format-V records are acceptable to the punch only. The device control character, 
if specified in the RECFM parameter, is used to select the stacker; it 1s not 
punched. The first 4 bytes (record descriptor word or segment descriptor word) of 
format-V records or record segments are not punched. For format-V records, at 
least 1 byte of data must follow the record or segment descriptor word or the 
carriage control character. 


Each punched card corresponds to one physical record. Therefore, you should 
restrict the maximum record size to 80 (EBCDIC mode) or 160 (column binary 
mode) data bytes. When mode (C) is used for the card punch, BLKSIZE must 
be 160 unless you are using PUT. Then you can specify BLKSIZE as 160 or a 
multiple of 160, and the system handles this as described under “PUT—Whnitte a 
Record” on page 66. You can specify the read/punch mode of operation 
(MODE) parameter as either card image (column binary) mode (C) or EBCDIC 
mode (E). If this information is omitted, E is assumed. The stacker selection 
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( - parameter (STACK) can be specified as either 1 or 2 to show which bin is to 
receive the card. If it is not specified, 1 1s assumed. 


For all QSAM, RECFM= BB, card punch data sets, the block size in the DCB 
will be adjusted by the system to equal the logical record length. This data set 
will be treated as RECFM=F. If the system builds the buffers for this data set, 
the buffer length will be determined by the BUFL parameter. If the BUFL 
parameter was not specified, the adjusted block size is used for the buffer length. 


If the DCB 1s to be reused with a block size larger than the logical record length, 
you must reset DCBBLKSI in the DCB and ensure that the buffers are large 
enough to contain the largest block size expected. You may ensure the buffer 
size by specifying the BUFL parameter before the first time the data set is opened 
or by issuing the FREEPOOL macro after each CLOSE macro so the system 
will build a new buffer pool of the correct size each time the data set is opened. 


Punch error correction on the IBM 2540 Card Read Punch is not performed. 


The IBM 3525 Card Punch accepts only format-F records for print data sets and 
for associated data sets. Other record formats are allowed for the read data set, 
the punch data set, and the interpret punch data set. For more information on 
programming for the 3525 Card Punch, see OS and OS/VS Programming Support — 
for the IBM 3505 Card Reader and [BM 3525 Card Punch. 


( . Printer 


With the IBM 3800 Printing Subsystem, the data in the record can contain two 
optional bytes—the optional control character used for carriage control, followed 
by an optional table reference character used for dynamically selecting a character 
arrangement table during printing. These characters are discussed below. 


Carriage Control Character 


You may specify in the DD statement, the DCB macro, or the data set label that 
an optional control character is part of each record in the data set. The 1-byte 
character is used to show a carnage control function when the data set is printed 
or a stacker bin when the data set is punched. Although the character 1s a part of 
the record in storage, it is never printed or punched. Note that buffer areas must 
be large enough to accommodate the character. If the immediate destination of 
the record 1s a device, such as a disk, that does not recognize the control 
character, the system assumes that the control character is the first byte of the 
data portion of the record. If the destination of the record is a printer or punch 
and you have not indicated the presence of a control character, the system regards 
the control character as the first byte of data. A list of the control characters is in 
Appendix B, “Control Characters” on page 213. 
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3800 Table Reference Character d ‘ 
| <4 4 
The 3800 table reference character is a numeric character (0, 1, 2, or 3) 
corresponding to the order in which the character arrangement table names have 
been specified with the CHARS keyword. It is used for selection of a character 
arrangement table during printing. (For more information on the table reference 
character, see [BM 3800 Printing Subsystem Programmer's Guide.) 


A numeric table reference character (such as 0) selects from within the table that 
font to which the character corresponds. The characters’ number values represent 
the order in which the font names have been specified with the CHARS 
parameter. In addition to using table reference characters to correspond to font 
names specified on the CHARS parameter, you can also code table reference 
characters that correspond to font names specified in PAGEDEF control 
structure. Valid table reference characters vary and range between 0 and 126. 
Table reference characters with values greater than 126 default to a value of 0 
(zero). For additional information, see JBM 3800 Printing Subsystem 
Programmer's Guide. 


Record Formats 


Records of format-F, -V, and -U are acceptable to the printer. The first 4 bytes 
(record descriptor word or segment descriptor word) of format-V records or 
record segments are not printed. For format-V records, at least 1 byte of data 
must follow the record or segment descriptor word or the carriage control 
character. The carriage control character, if specified in the RECFM parameter, is | 
not printed. The system does not position the printer to channel | for the first Mee 
record unless specified by a carriage control character. 


ao 


Because each line of print corresponds to one record, the record length should 
not exceed the length of one line on the printer. For variable-length spanned 
records, each line corresponds to one record segment, and block size should not 
exceed the length of one line on the pmnter. 


If carriage control characters are not specified, you can show printer spacing 
(PRTSP) as 0, 1, 2, or 3. If it is not specified, 1 is assumed. | 


For all QSAM, RECFM= FB, printer data sets, the block size in the DCB will 
be adjusted by the system to equal the logical record length. This data set will be 
treated as RECFM=F. If the system builds the buffers for this data set, the 
buffer length will be determined by the BUFL parameter. If the BUFL 
parameter was not specified, the adjusted block size is used for the buffer length. 


If the DCB is to be reused with a block size larger than the logical record length, 
you must reset DCBBLKSI in the DCB and ensure that the buffers are large 
enough to contain the largest block size expected. You may ensure the buffer 
size by specifying the BUFL parameter before the first time the data set is opened 
or by issuing the FREEPOOL macro after each CLOSE macro so the system 
will build a new buffer pool of the correct size each time the data set is opened. 
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Direct Access Device 





Direct access devices accept records of format-F, -V, or -U. If the records are to 
be read or wnitten with keys, the key length (KEYLEN) must be specified. In 
addition, the operating system has a standard track format for all direct access 
volumes. Each track contains data information and certain control information 
such as: 


e The address of the track 

e The address of each record 
e The length of each record 
e Gaps between areas 


A complete description of track format is contained in “Direct Access Volumes” 
on page 5. 


Chapter 3. Record Formats 33 





















































Chapter 4. Selecting an Access Method 


The operating system allows you to concentrate most of your efforts on 
processing the records read or written by the data management routines. To get 
the records read and written, your main responsibility is to describe the data set 
to be processed, the buffering techniques to be used, and the access method. An 
access method has been defined as the combination of data set organization and 
the technique (queued or basic) used to gain access to the data. 


Overview of Access Methods 


Access methods are identified primarily by the data set organization to which 
they apply. For instance, BDAM is the basic access method for direct 
organization. Nevertheless, there are times when an access method identified 
with one organization can be used to process a data set usually thought of as 
organized in a different manner. Thus, a data set created by the basic access 
method for sequential organization (BSAM) may be processed by the basic direct 
access method (BDAM) and visa versa. If the queued access technique is used to 
process a sequential data set, the access method is called the queued sequential 
access method (QSAM). 


Basic access methods are used for all data organizations, while queued access 
methods apply only to sequential and indexed sequential data sets as shown in 


Figure 13. 

Data Set Access Technique 
Organization Basic Queued 
Sequential BSAM QSAM 
Partitioned BPAM 

Indexed Sequential BISAM QISAM 
Direct BDAM 


Figure 13. Data Management Access Methods 


It is possible to control an I/O device directly while processing a data set with 
any data organization without using a specific access method. The execute 
channel program (EXCP) macro instruction uses the system programs that 
provide for scheduling and queuing I/O requests, efficient use of channels and 
devices, data protection, interruption procedures, error recognition, and retry. 
Complete details about the EXCP macro are in System-Data Administration. 
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Temporary data sets can be handled by a function called virtual I/O (VIO). Data 
sets for which VIO is specified are located in external page storage. However, to 
the access methods (BDAM, BPAM, BSAM, QSAM, and EXCP), the data sets 
appear to reside on a real direct access storage device. VIO provides these 
advantages: 


e Elimination of some of the usual I/O device allocation and data management 
overhead for temporary data sets 


e Generally more efficient use of direct access storage space 


To use VIO, you must specify VIO = YES in the UNITNAME macro during 
system generation, and you must specify a unitname (defined in the 
UNITNAME macro) on the DD statement for your data set. For additional 
information on VIO, see Initialization and Tuning Guide. For information on the 
UNITNAME macro, see System Generation Reference. For information on 
changes to the DD statement, see JCL. 


Basic Direct Access Method (BDAM) | 


Before you use the BDAM access method to process a data set, consider these 

implications: 

e You create a BDAM data set with the basic sequential access method 
(BSAM). A special operand in the BSAM DCB macro (MACRF = WL) 
shows that you want to create a BDAM data set. 


e The problem program must synchronize all I/O operations with a CHECK 
or a WAIT macro. 


e The problem program must block and unblock its own input and output 
records. (BDAM only reads and wnites data blocks.) 


e You can find data blocks within a data set with one of the following 
addressing techniques: 


— Actual device addresses. 


— Relative track address technique. This locates a track on a direct access 
device relative to the ¢ beginning of the data set. 


— Relative block address technique. This locates a fixed-length data block 
relative to the beginning of the data set. 


For more information about coding the DCB macro to process a BDAM data 
set, see Data Administration: Macro Instruction Reference. 
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Basic Indexed Sequential Access Method (BISAM) 


Before you use the BISAM access method to process an ISAM data set, consider 
these implications: 


BISAM accesses only ISAM data sets. 


BISAM cannot be used to create an indexed sequential access method 
(ISAM) data set. 


BISAM directly retrieves logical records by key, updates blocks of records 
in-place, and inserts new records in their correct key sequence. 


The problem program must synchronize all I/O operations with a CHECK 
or a WAIT macro. 


Other DCB operands are available to reduce input/output operations by 
defining work areas that contain the highest level master index and the 
records being processed. 


For more information about coding the DCB macro to process a BISAM data 
set, see Data Administration: Macro Instruction Reference. 


Basic Partitioned Access Method (BPAM) 


( BPAM is a subset of BSAM, which processes only the directory of a partitioned 
data set. BSAM processes the data set members. 


Before you use the BPAM access method to process a data set, consider these 
implications: 





One complete partitioned data set must be on one direct-access volume, but 
you can concatenate multiple input data sets that are on the same or different 
volumes. 


When you create a partitioned data set, you must specify the SPACE 
parameter on your first (or only) DD statement for the data set. This 
parameter defines the size of the data set and its directory so that the system 
can allocate data set space and pre-format the directory. 


You can use either the basic sequential access method (BSAM) or the 
queued sequential access method (QSAM) to add or retrieve a BPAM data 
set member without specifying the BLDL, FIND, or the STOW macro by 
coding the DSORG = PS operand in the DCB macro. (Data set positioning 
and directory maintenance are then handled by the OPEN and CLOSE 
macros.) But, be advised that you are really processing the member as if it 
were part of a sequential data set, so you are not using the complete 
capabilities of BPAM. 


You can use the STOW macro to add, delete, change, or replace an element 
name or alias in the directory. 
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You can process multiple data set members by passing a list of members to 
BLDL. Then you can use the FIND macro to position to a member before 
processing it. 


For more information about coding the DCB macro to process a BPAM data 
set, see Data Administration: Macro Instruction Reference. 


Basic Sequential Access Method (BSAM) 


Before you use the BSAM access method to process a data set, consider these 
implications: 


The problem program must block and unblock its own input and output 
records. (BSAM only reads and writes data blocks.) 


The problem program must manage its own input and output buffers. It 
must give BSAM a buffer address with the READ macro, and it must fill its 


own output buffer before issuing the WRITE macro. 


The problem program must synchronize its own I/O operations by issuing a 
CHECK macro for each READ and WRITE macro issued. 


BSAM lets you process nonsequential blocks by repositioning with the 
NOTE and POINT macros. 


You can read and write direct access device record keys with BSAM. 


For more information about coding the DCB macro to process a BSAM data 
set, see Data Administration: Macro Instruction Reference. 


Queued Indexed Sequential Access Method (QISAM) 


Before you use the QISAM access method to process an ISAM data set, consider 
these implications: | 


The characteristics of a QISAM data set are established when the data set is 
created. You can’t change them without reorganizing the data set. The 
DCB operands that establish these characteristics are: BLKSIZE, CYLOFL, 
KEYLEN, LRECL, NIM, OPTCD, RECFM, and RKP. 


A QISAM data set can consist of unblocked fixed-length records (F), blocked 
fixed-length records (FB), unblocked variable-length records (V), or blocked 
variable-length records (VB). 


QISAM can create an indexed sequential data set (QISAM, load mode), add 
additional data records at the end of the existing data set (QISAM, resume 
load mode), update a record in place, or retrieve records sequentially 
(QISAM, scan mode). 


You can’t use track overflow to create or extend an ISAM data set. 
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When you create an indexed sequential data set, you can allocate space for 
the data set’s prime area, overflow area, and its cylinder/master index(es) on 
the same or separate volumes. For more information about space allocation, 
see JCL. 


QISAM automatically generates a track index for each cylinder in the data set 
and one cylinder index for the entire data set. Specify the DCB operands 
NIM and OPTCD to show that the data set requires a master index(es). 
QISAM creates and maintains as many as three levels of master indexes. 


You can purge records by specifying the OPTCD = L DCB option when you 
create an ISAM data set. This option flags the records you want to purge 
with a X’FF’ in the first data byte of a fixed-length record or the fifth byte of 
a variable-length record. QISAM ignores these flagged records during 
sequential retrieval. 


You can get reorganization statistics by specifying the OPTCD = R DCB 
option when an ISAM data set is created. The problem program uses these 
statistics to determine the status of the the data set’s overflow areas. 


When you create an ISAM data set, you must write the records in ascending 
key order. 


For more information about coding the DCB macro to process a QISAM data 
set, see Data Administration: Macro Instruction Reference. 


Queued Sequential Access Method (QSAM) 


Before you use the QSAM access method to process a data set, consider these 
implications: 


You can use QSAM to process all record formats except blocks with keys. 
QSAM blocks and unblocks records for you automatically. 


QSAM manages all aspects of I/O buffering for you automatically. The 
GET macro retrieves the next sequential logical record from the input buffer, 
and the PUT macro places the next sequential logical record in the output 
buffer. 


QSAM gives you three transmittal modes: move, locate, and data. These 
modes give you greater flexibility managing buffers and moving data. 


For more information about coding the DCB macro to process a QSAM data 
set, see Data Administration: Macro Instruction Reference. 
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Chapter 5. Specifying a Data Control Block and Initializing Data Sets 


Before processing can begin, you must identify the characteristics of a data set, 
the volume on which it resides, and its processing requirements. During 
execution, this information is made available to the operating system in the data 
control block (DCB). A DCB is required for each data set and is created in a 
processing program by a DCB macro instruction. 


Primary sources of information to be placed in the data control block are a DCB 
macro instruction, a data definition (DD) statement, and a data set label. In 
addition, you can provide or change some of the information during execution by 
storing the pertinent data in the appropriate field of the data control block. The 
specifications needed for input/output operations are supplied during the 
initialization procedures of the OPEN macro instruction. Therefore, the 
pertinent data can be provided when your job is to be executed rather than when 
you write your program (see Figure 14 on page 42). 


When the OPEN macro instruction is executed, the OPEN routine: 

e Completes the data control block 

e Loads all necessary access method routines not already in virtual storage 
e Initializes data sets by reading or writing labels and control information 
e Builds the necessary Pen control bivcks 


Information from a DD statement is stored in the job file control block (JFCB) 
by the operating system. When the job is to be executed, the JFCB is made 
available to the open routine. The data control block is filled in with information 
from the DCB macro instruction, the JFCB, or an existing data set label. If 
more than one source specifies information for a particular field, only one source 
is used. A DD statement takes precedence over a data set label, and a DCB 
macro instruction over both. However, you can change most data control block 
fields either before the data set is opened or when the operating system returns 
control to your program (at the data control block open exit). Some fields can 
be changed during processing. 


Figure 14 on page 42 illustrates the process and the sequence of filling in the 
data control block from various sources. The primary source is your program, 
that is, the DCB macro instruction. In general, you should use only those DCB 
parameters that are needed to ensure correct processing. The other parameters 
can be filled in when your program 1s to be executed. 
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When a direct access data set is opened (or a magnetic tape with standard labels 
is opened for INPUT, RDBACK, or INOUT), any field in the JFCB not 
completed by a DD statement is filled in from the data set label (if one exists). 
When opening a magnetic tape for output, the tape label 1s assumed not to exist 
or to apply to the current data set unless you specify DISP = MOD and a volume 
serial number in the volume parameter of the DD statement. Any field not 
completed in the DCB is filled in from the JFCB. Fields in the DCB can then 
be completed or changed by your own DCB exit routine. Then all DCB fields 
are unconditionally merged into corresponding JFCB fields if your data set is 
opened for output. This is done by specifying OUTPUT, OUTIN, EXTEND, 
or OUTINX in the OPEN macro instruction. The DSORG field is not merged 
unless this field contains zeros in the JFCB. If your data set is opened for input 
(INPUT, INOUT, RDBACK, or UPDAT is specified in the OPEN macro 
instruction), the DCB fields are not merged unless the corresponding JFCB fields 
contain zeros. | 
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Figure 14. Sources and Sequence of Operations for Completing the Data Control Block 


When the data set is closed, the data control block is restored to the condition it 
had before the data set was opened (the buffer pool is not freed). The open and 
close routines also use the updated JFCB to write the data set labels for output 
data sets. If the data set is not closed when your program terminates, the 
operating system will close it automatically. 


The operating system requires several types of processing information to ensure 
proper control of your input/output operations. The forms of macros 1n the 
program, buffering requirements, and the addresses of your special processing 
routines must be specified during either the assembly or the execution of your 
program. The DCB parameters specifying buffer requirements are discussed in 
“Managing SAM Buffer Space” on page 119. 


Because macros are expanded during the assembly of your program, you must 
supply the macro forms that are to be used in processing each data set in the 
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associated DCB macro. You can supply buffering requirements and related 
information in the DCB macro, the DD statement, or by storing the pertinent 
data in the appropriate field of the data control block before the end of your 
DCB exit routine. If the addresses of special processing routines (EODAD, 
SYNAD, or user exits) are omitted from the DCB macro, you must complete 
them in the DCB before they are required. 


Note: A data set label to JFCB merge is not performed for concatenated data 
sets at the end-of-volume time. If you want a merge, turn on the unlike attribute 
bit (DCBOFPPC) in the DCB. This attribute forces the system through OPEN 
for each data set in the concatenation, where a label to JFCB merge takes place. 


Selecting Data Set Options 


DCB Parameters 


For each data set you want to process, there must be a corresponding DCB and 
DD statement. The characteristics of the data set and device-dependent 
information can be supplied by either source. Also, the DD statement must 
supply data set identification, device characteristics, space allocation requests, and 
related information as specified in /CL. You establish the logical connection 
between a DCB and a DD statement by specifying the name of the DD 
statement in the DDNAME field of the DCB macro, or by completing the field 
yourself before opening the data set. 


After you have specified the data set characteristics in the DCB macro, you can 
change them only by changing the DCB during execution. The fields of the 
DCB discussed below are common to most data organizations and access 
techniques. (For more information about the DCB fields, see Data 
Administration: Macro Instruction Reference.) 


Block Size (BLKSIZE): Specifies the maximum length, in bytes, of a data 
block. If the records are of format F, the block size must be an integral multiple 
of the record length, except for SYSOUT data sets. (See Chapter 8, “Spooling 
and Scheduling Data Sets” on page 105.) Ifthe records are of format V, the 
block size specified must be the maximum block size. If format-V records are 
unblocked, the block size must be 4 bytes greater than the record length 
(LRECL). When spanned variable-length records are specified, the block size is 
independent of the record length. For ISO/ANSI/FIPS Version 3 records, the 
maximum block size is 2048. 


There is no minimum requirement for block size; however, if a data check occurs 
on a magnetic tape device, any block shorter than 12 bytes in a read operation or 
18 bytes in a write operation is treated as a noise record and lost. No check for _ 
noise is made unless a data check occurs. The maximum block size for an 
ISO/ANSI/FIPS Version 3 tape is 2048 bytes. This limit may be overridden by a 
label validation installation exit. (See Magnetic Tape Labels and File Structure.) 
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Data Set Organization (DSORG): Specifies the organization of the data set as a > 


physical sequential (PS), indexed sequential (IS), partitioned (PO), or direct 
(DA). If the data set is processed using absolute rather than relative addresses, 
you must mark it as unmovable by adding a U to the DSORG parameter (for 
example, by coding DSORG= PSU). You must specify the data set organization 
in the DCB macro. When creating or processing an indexed sequential 
organization data set or creating a direct data set, you must also specify DSORG 
in the DD statement. When creating a direct data set, the DSORG in the DCB 
macro must specify PS or PSU and the DD statement must specify DA or DAU. 


Key Length (KEYLEN): Specifies the length (0 to 255) in bytes of an optional 
key that precedes each block on a direct access device. The value of KEYLEN is 
not included in BLKSIZE or LRECL but must be included in BUFL if buffer 
length is specified. Thus, BUFL= KEYLEN + BLKSIZE. 


Record Length (LRECL): Specifies the length, in bytes, of each record in the 
data set. If the records are of variable length, the maximum record length must 
be specified. For input, the field should be omitted for format-U records. For 
the extended logical record interface for ISO/ANSI/FIPS variable spanned 
records, LRECL must be specified as LRECL=0K or LRECL=nkK. 


Record Format (RECFM): Specifies the characteristics of the records in the data 
set as fixed-length (F), variable-length (V), ISCII/ASCII variable-length (D), or 
undefined-length (U). Blocked records are specified as FB, VB, or DB. Spanned 
records are specified as VS, VBS, DS, or DBS. (ISCH/ASCII records are 
specified as DS or DBS.) You may also specify the records as fixed-length 
standard by using FS or FBS. You can request track overflow for records other 
than standard format by adding a T to the RECFM parameter (for example, by 
coding FBT). 


The type of print control can be specified to be in ANSI format-A or in machine 
code format-M, as described in Appendix B, “Control Characters” on page 213. 


Write Validity Check Option (OPTCD=W): You can specify the write validity 
check option in either the DCB parameter of the DD statement or the DCB 
macro. After a record 1s transferred from main to secondary storage, the system 
reads the stored record (without data transfer) and, by testing for a data check 
from the I/O device, verifies that the record was written correctly. Be aware that 
the write validity check process requires an additional revolution of the device for 
each record. If the system detects any errors, it starts its standard error recovery 
procedure. 


For buffered tape devices, the write validity check option delays the device end 
interrupt until the data is physically on tape. When you use the 
write-validity-check option, you get none of the performance benefits of 
buffering. 
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DD Statement Parameters 


Each of the data set description fields of the data control block, except as noted 
for data set organization, can be specified when your job is to be executed. Also, 
data set identification and disposition, and device characteristics, can be specified 
at that time. The parameters of the DD statement discussed below are common 
to most data set organizations and devices. (See JCL.) 


Device Affinity (AFF): Requests that specified data sets be allocated to the same 
device. 


Data Control Block (DCB): Provides, through sub parameters, information to 
be used to complete those fields of the data control block that were not specified 
in the DCB macro. This parameter cannot be used to change data control block 
fields that are specified in the user’s program. 


Data Definition Name (DDNAME): 1s the name of the DD statement and 
connects the DD statement to the data control block that specifies the same 
DDNAME. 


Data Set Disposition (DISP): Describes the status (OLD, NEW, KEEP, or 
DELETE) of a data set and shows what is to be done with it at the end of the 
job step. 


Data Set Name (DSNAME): Specifies the name of a newly defined data set, or 
refers to a previously defined data set. 


Data Set Label (LABEL): Shows the type and contents of the tape label or 
labels associated with the data set. The operating system verifies standard labels. 
Standard labels include those specified in the DD statement as SL (standard 
labels), SUL (standard user labels), AL (American National Standard labels), and 
AUL (American National Standard user labels). Nonstandard labels (NSL) can 
be specified only if your installation has incorporated into the operating system 
routines to write and process nonstandard labels. 


Space Allocation (SPACE): Designates the amount of space on a direct access 
volume that should be allocated for the data set. Unused space can be released, if 
requested, when your job is finished. 


Input[Output Device (UNIT): Specifies the number or type of I/O devices to be 


allocated for use by the data set. 


Volume Identification (VOLUME): Identifies the particular volume or volumes, 
or the number of volumes, to be assigned to the data set, or the volumes on 
which existing data sets reside. 
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Changing the DCB 


You can complete or change the DCB during execution of your program. You 
can also determine data set characteristics from information supplied by the data 
set labels. You can make changes or additions before you open a data set, after 
you close it, during the DCB open exit routine, or while the data set is open. 
Naturally, you must supply the information before it is needed. 


Use the data control block DSECT (DCBD) macro to identify the DCB field 
names symbolically. If you load a base register with the DCB address, you can 
refer to any field symbolically. 


The DCBD macro generates a dummy control section (DSECT) named 
IHADCB. Each field name symbol consists of DCB followed by the first 5 
letters of the keyword operand for the DCB macro. For example, the symbolic 
name of the block size operand field is DCBBLKSI. (For other DCB field 
names, see Data Administration: Macro Instruction Reference.) 


The attributes of each DCB field are defined in the dummy control section. Use 
the DCB macro’s assembly listing to determine the length attribute and the 
alignment of each DCB field. 

You can code the DCBD macro once to describe all DCBs. 


Changing an Address in the Data Control Block: eae 15 shows you how to 
change a field in the data control block. 


~ QPEN (TEXTDCB , INOUT) 
EOFEXIT CLOSE (TEXTDCB , REREAD) , TYPE=T 
LA 10, TEXTDCB 
USING  IHADCB, 10 
MVC DCBSYNAD+1(3) ,=AL3(OUTERROR) 
B OUTPUT 
INERROR STM 14, 12, SYNADSA+12 
OUTERROR  ST™ 14,12, SYNADSA+12 
TEXTDCB DCB DSORG=PS , MACRF=(R,W) , DDNAME=TEXTTAPE, 
 EODAD=EOFEXIT, SYNAD=INERROR 


DCBD DSORG=PS 


Figure 15. Changing a Field in the Data Control Block 


The data set defined by the data control block TEXTDCB is opened for both 
input and output. When the problem program no longer needs it for input, the 
EODAD routine closes the data set temporarily to reposition the volume for 


output. The EQDAD routine then uses the dummy control section IHADCB to 


change the error exit address (SYNAD) from INERROR to OUTERROR. 


The EODAD routine loads the address TEXTDCB into register 10, the base 


_ register for IHADCB. Then it moves the address OUTERROR into the 
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DCBSYNAD field of the DCB. Even though DCBSYNAD is a fullword field 
and contains important information in the high-order byte, change only the 3 
low-order bytes in the field. 


All unused address fields in the DCB, except DCBEXLST, are set to 1 when the 
DCB macro is expanded. Many system routines interpret a value of | in an 
address field as meaning no address was specified, SO use it to dynamically reset 
any field you don’t need. 


Opening and Closing a Data Set 


Although your program has been assembled, the various data management 
routines required for I/O operations are not a part of the object code. In other 
words, your program is not completely assembled until the DCBs are initialized 
for execution. You initialize by issuing the OPEN macro instruction to open a 
data set. After all DCBs have been completed, the system ensures that all 
required access method routines are loaded and ready for use and that all channel 
programs and buffer areas are ready. | 


Access method routines are selected and loaded according to data control fields 
that indicate: 


e Data organization 

e Buffering technique 

e Recess technique 

e J/O unit characteristics 
@ = =Record format 


This information 1s used by the system to allocate virtual storage space and load 
the appropriate routines. These routines, the channel programs and buffer areas 
created automatically by the system, remain in virtual storage until the close 

routine signals that they are no longer needed by the DCB that was using them. 


When I/O operations for a data set are completed, you should issue a CLOSE 
macro instruction to return the DCB to its original status, handle volume 
disposition, create data set labels, complete writing of queued output buffers, and 
free virtual and auxiliary storage. | 


Managing Buffer Pools When Closing Data Sets 


After closing the data set, you should issue a FREEPOOL macro instruction to 
release the virtual storage used for the buffer pool. If you plan to process other 
data sets, use FREEPOOL to regain the buffer pool storage space. If you expect 
to reopen a data set using the same DCB, use FREEPOOL unless the buffer 

ae pool created the first tume the data set was opened will meet your needs when 

( : you reopen the data set. (FREEPOOL is discussed in more detail 1 in “Buffer 

— Pool Construction” on page 120.) 
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After the data set has been closed, the DCB can be used for another data set. If 
you do not close the data set before a task terminates, the operating system closes 
it automatically. If the DCB is not available to the system at that time, the 
operating system abnormally ends the task, and data results can be unpredictable. 
Note, however, that the operating system cannot automatically close any open 
data sets after the normal end of a program that was brought into virtual storage 
by the loader. Therefore, loaded programs must include CLOSE macro 
instructions for all open data sets. . 


Simultaneous Opening and Closing of Multiple Data Sets 


An OPEN or CLOSE macro instruction can be used to begin or end processing 
of more than one data set. Simultaneous opening or closing is faster than issuing 


separate macro instructions; however, additional storage space is required for each 


data set specified. The coding examples in Figure 16 on page 52 and Figure 18 
on page 54 show the macro expansions for simultaneous open and close 
operations. _ 


Opening and Closing Data Sets Shared by More Than One Task 


When more than one task is sharing a data set, the following restrictions must be 
recognized. Failure to adhere to these restrictions endangers the integrity of the 
shared data set. 


e All tasks sharing a DCB must be in the job step that opened the DCB (see 
“Sharing Data Sets” on page 69). 


e Each task sharing a DCB must ensure that all the input and output 
operations it starts using a given DCB are complete, before the task 
terminates. A CLOSE macro instruction issued for the DCB will ensure 
termination of all input and output operations. 


e A DCB can be closed only by the task that opened it. 
Considerations for Allocating Direct Access Data Sets 


When you allocate space for a new data set on a direct access volume, the tracks 
contain unknown data. A program that tries to access data on these tracks before 
known data is written on them may get unpredictable results, such as program 
checks or I/O errors. The program may even appear to run correctly! 


If you must access a newly allocated data set before you put known data into it, 
use one of the following methods to make it appear empty: 


1. At allocation time, specify a primary allocation value of zero; such as 
SPACE = (TRK,(0,10)) or SPACE =(CYL,(0,50)). This method prevents 
processing certain labels if user labels are requested (LABEL=(,SUL)). 


2. After allocation time, run a program that opens the data set for output and 


closes it without writing anything. This puts an end-of-file mark at the 
beginning of the data set. 
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( = Considerations for Opening and Closing Data Sets 


e Two or more DCBs should never be concurrently open for output to the 
same data set, except with the basic indexed sequential access method 
(BISAM). | 


e If, concurrently, one DCB is open for input or update, and one for output to 
the same data set on a direct access device, the input or update DCB may be 
unable to read what the output DCB wrote if the output DCB extended the 
data set. Ce 


e If you want to use the same DD statement for two or more DCBs, you 
cannot specify parameters for fields in the first DCB and then be assured of 
obtaining the default parameters for the same fields in any other DCB using 
the same DD statement. This is true for both input and output and is 
especially important when you are using more than one access method. Any 
action on one DCB that alters the JFCB affects the other DCBs and thus 
can cause unpredictable results. Therefore, unless the parameters of all DCBs 
using one DD statement are the same, you should use separate DD 
statements. 


e Associated data sets for the IBM 3525 Card Punch can be opened in any 
order, but all data sets must be opened before any processing can begin. 
Associated data sets can be closed in any order, but, after a data set has been 
7 closed, I/O operations cannot be performed on any of the associated data 
( % sets. See Programming Support for the IBM 3505 Card Reader and the IBM 
| 3525 Card Punch for more information. 


e¢ The OPEN macro gets user control blocks and user storage in the protection 
key that is specified in the TCB(TCBPKF). Therefore, any task that 
processes the DCB (such as Open, Close, or EOV) must be in the same 
protection key specified in the TCB, or must be in key 0. Also, the Open 
and Close must be done 1n the same key. 


| Note: If the Open is done while processing in key 0, then user storage 
| obtained by Open will be from subpool 252. 


e Volume disposition specified in the OPEN or CLOSE macro instruction can 
be overridden, by the system if necessary. However, you need not be 
concerned; the system automatically requests the mounting and demounting 
of volumes, depending on the availability of devices at a particular time. 
Additional information on volume disposition is provided in JCL. 


Open/Close/EOV Errors 


There are two classes of errors that can occur during open, close, and 
end-of-volume processing: determinate and indeterminate errors. Determinate 
errors are errors associated with a system completion code. For example, a 
condition associated with the 213 completion code with a return code of 04 might 
be detected during open processing, indicating that a format-1 DSCB could not 
be found for a data set being opened. Indeterminate errors are errors that cannot 
be anticipated, such as program checks. 





Chapter 5. Specifying a Data Control Block and Initializing Data Sets 49 











If a determinate error occurs during the processing resulting from a concurrent 
OPEN or CLOSE macro instruction, an attempt will be made to complete open 
or close processing of the DCBs that are riot associated with the DCB in error. 
Note that you can also choose to abnormally end the task immediately by coding 
a DCB abend exit routine that shows the “immediate termination” option (see 
“DCB Abend Exit” on page 97). When all open or close processing is 
completed, abnormal end processing is begun. Abnormal end involves forcing all 
DCBs associated with a given OPEN or CLOSE macro to close status, thereby 
freeing all storage devices and other system resources related to the DCBs. 


If an indeterminate error (such as a program check) occurs during open, close, or 
EOV processing, no attempt is made by the system control program to complete 
concurrent open or close processing. The DCBs associated with the OPEN or 
CLOSE macro are forced to close status if possible, and the resources related to 
each DCB are freed. 


To determine the status of any DCB after an error, the OPEN (CLOSE) return 
code in register 15 must be interrogated for the following values: 


Return Code Meaning 


00 (X’00’) All entries in the parameter list opened successfully. 

04 (X’04’) All entries in the parameter list have successfully 
completed open, but one or more entries have a , warning 
message. 

08 (X’08") One or more entries in the parameter list were not 

| opened successfully. The entries with errors are restored 
to their preopen status. 

12 (X’0C’) One or more entries in the parameter list were not 

| opened successfully. 


The entries with errors are not restored, and cannot be reopened without 
restoration. 


During task termination, the system issues a CLOSE macro for each data set that 
is still open. If this is an abnormal termination for QSAM, the close routines 
that would normally finish processing buffers are bypassed. Any outstanding I/O 
requests are purged. Thus, your last data records may be lost for a QSAM 
output data set. 


It is a good procedure to close an ISAM data set before task termination because, 


if an I/O error is detected, the ISAM close routines cannot return the problem 
program registers to the SYNAD routine, causing unpredictable results. 


Installation exits 


Four installation exit routines are provided for abnormal end with 
ISO/ANSI/FIPS Version 3 tapes. 


¢ The label validation exit is entered during open/EOV if an invalid label 
condition 1s detected, and label validation has not been suppressed. Invalid 
conditions include incorrect alphameric fields, nonstandard values (for 
example, RECFM =U, block size greater than 2048, or a zero generation 
number), invalid label sequence, nonsymmetrical labels, invalid expiration 
date sequence, and duplicate data set names. 
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e The validation suppression exit is entered during open/EOV if volume 
security checking has been suppressed, if the volume label accessibility field 
contains an ISCII/ASCII space character, or if RACF accepts a volume and 
the accessibility field does not contain an uppercase A through Z. 


e The volume access exit is entered during open/EOV if a volume is not 
RACE protected and the accessibility field in the volume label contains an 
ISCII/ASCII uppercase A through Z. 


e The file access exit is entered after positioning to a requested data set if the 
accessibility field in the HDR1 label contains an ISCII/ASCII uppercase A 
through Z. 


For additional information about ISO/ANSI/FIPS Version 3 installation exits, 
see Magnetic Tape Labels and File Structure. 


OPEN—Prepare a Data Set for Processing 


Processing Method 


The OPEN macro instruction is used to complete a data control block for an 
associated data set. The OPEN macro parameters identify the method of 
processing and volume positioning in the event of an end-of-volume condition. 


You can process a data set as either input or output. This is done by coding 
INPUT, OUTPUT, or EXTEND as the processing method operand of the 
OPEN macro. For BSAM, code INOUT, OUTIN, or OUTINX. If the data set 
resides on a direct access volume, you can code UPDAT in the processing 
method operand to show that records can be updated. By coding RDBACK in 
this operand, you can specify that a magnetic tape volume containing format-F 
or format-U records is to be read backward. (Variable-length records cannot be 
read backward.) If the processing method operand is omitted from the OPEN 
macro instruction, INPUT is assumed. The operand is ignored by the basic 
indexed sequential access method (BISAM); it must be specified as OUTPUT or 
EXTEND when you are using the queued indexed sequential access method 
(QISAM) to create an indexed sequential data set. You can override the INOUT, 
OUTIN, UPDAT, or OUTINX at execution time by using the LABEL 
parameter of the DD statement, as discussed in /CL. 


Note: Unless label validation has been suppressed, OPEN for MOD (OLD 
OUTPUT/OUTIN), INOUT, EXTEND, or OUTINX cannot be processed for 
ISO/ANSI/FIPS Version 3 tapes, because this kind of processing updates only 
the closing label of the file, causing a label symmetry conflict. An unmatching 
label should not frame the other end of the file. 


SYSIN and SYSOUT data sets must be opened for INPUT and OUTPUT, 
respectively. INOUT is treated as INPUT; OUTIN, EXTEND, or OUTINX is 
treated as OUTPUT. UPDAT and RDBACK cannot be used. 


In Figure 16 on page 52, the data sets associated with three DCBs are to be 
opened simultaneously. 
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OPEN (TEXTDCB, , CONVDCB, (OUTPUT) , PRINTDCB, = 
(OUTPUT) ) : 
+ CNOP 0,4 : Align list to fullword 
+ BAL 1,*+16 Load regl w/list address 
+ DC AL1(0) Option byte 
+ DC AL3 (TEXTDCB ) DCB address 
+ ~—~De AL1(15) Option byte 
+ DC AL3(CONVDCB ) DCB address 
+ DC AL1(143) Option byte 
+ DC AL3(PRINTDCB) DCB address 
+ SVC 19 Issue open SVC 


Figure 16. Opening Three Data Sets Simultaneously 


Because no processing method operand 1s specified for TEXTDCB, the system 
assumes INPUT. Both CONVDCB and PRINTDCB are opened for output. 
No volume positioning options are specified; thus, the disposition indicated by 
the DD statement DISP parameter is used. 


At execution, the SVC 19 instruction passes control to the open routine, which 
initializes the three DCBs and loads the appropriate access method routines. 


CLOSE—Terminate Processing of a Data Set 


The CLOSE macro instruction is used to terminate processing of a data set and , 
release it from a DCB. The volume positioning (tapes only) that is to result from Ms 
closing the data set can also be specified. Volume positioning options are the 

same as those that can be specified for end-of-volume conditions in the OPEN 

macro instruction or the DD statement. An additional volume positioning 

option, REWIND, 1s available and can be specified by the CLOSE macro 

instruction for magnetic tape volumes. REWIND positions the tape at the load 

point regardless of the direction of processing. 


You can code CLOSE TYPE=T and perform some close functions for 
sequential data sets on magnetic tape and direct access volumes processed with 
BSAM. When you use TYPE=T, the DCB used to process the data set 
maintains its open status. You don’t have to issue another OPEN macro 
instruction to continue processing the same data set. This option cannot be used 
ina SYNAD routine. 


The TYPE=T operand causes the system control program to process labels, 
modify some of the fields in the system control blocks for that data set, and 
reposition the volume (or current volume in the case of multivolume data sets) in 
much the same way that the normal CLOSE macro does. When you code 
TYPE=T, you can specify that the volume is either to be positioned at the end 
of data (the LEAVE option) or to be repositioned at the beginning of data (the 
REREAD option). Magnetic tape volumes are repositioned either immediately 
before the first data record or immediately after the last data record; the presence 
of tape labels has no effect on repositioning. Figure 17 on page 53, which 
assumes a sample data set containing 1000 records, illustrates the relationship 
between each positioning option and the point where you resume processing the 
data set after issuing the temporary close. 
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(Fyou CLOSE TYPE =T ane specify After temporary close, you will 
resume processing 
LEAVE Immediately after record 1000 


LEAVE (with tape data set open Immediately before record 1 
for read backward) 
REREAD Immediately before record 1 


Immediately after record 1000 


Figure 17. Record Processed When LEAVE or REREAD Is Specified for CLOSE 
TYPE=T 
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If you code the release (RLSE) operand on the DD statement for an output data 
set, it is ignored by temporary close (CLOSE TYPE=T). However, if the last 
operation was a write, then normal close (without TYPE=T) releases any 
unused space. 


Space is released on a track boundary if the extent containing the last record was 
allocated in units of tracks or in units of average block lengths with ROUND not 
specified. Space is released on a cylinder boundary if the extent containing the last 
record was allocated in units of cylinders or in units of average block lengths with 
ROUND specified. However, a cylinder boundary extent may be released on a 


track boundary if: 


e The DD statement used to access the data set contains a space parameter 
specifying units of tracks or units of average block lengths with ROUND not 
specified, or 


e No space parameter is supplied in the DD statement and no secondary space 
value has been saved in the format-1 DSCB for the data set. (This may occur 
if the release indicator is set in the JFCB through RDJFCB and OPEN 
TYPE=J, or through the OPEN installation exit.) In this case, the 
performance benefit of cylinder boundaries is lost. 


For data sets processed with BSAM, you can use CLOSE TYPE=T with the 
following restrictions: 


e The DCB for the data set you are processing on a direct access device must 
specify either DSORG= PS or DSORG= PSU for input processing, and 
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either DSORG= PS, DSORG= PSU, DSORG= PO, or DSORG= POU for ff 
output processing. aw 


e The DCB must not be open for input to a member of a partitioned data set. 


e If you open a data set on a direct access device for output and issue CLOSE 
TYPE=T, the volume will be repositioned only if the data set was created 
with DSORG= PS, DSORG= PSU, DSORG= PO, or DSORG= POU 
(you cannot specify the REREAD option if DSORG= PO or 
DSORG= POU is specified). (This restriction prohibits the use of temporary 
close following or during the building of a BDAM data set that is created by 
specifying BSAM MACRF= WL.) 


e If you open the data set for input and issue CLOSE TYPE=T with the 
LEAVE option, the volume will be repositioned only if the oa set specifies 
DSORG= PS or DSORG= PO. 


Note: When a data control block is shared among multiple tasks, only the task 
that opened the data set can close it unless TYPE= T 1s specified. 


Before issuing the CLOSE macro, a CHECK macro must be issued for all 
DECBs that have outstanding I/O from WRITE macro instructions. When 
CLOSE TYPE= T 1s specified, a CHECK macro must be issued for all DECBs 
that have outstanding I/O from either WRITE or READ macro instructions. 


In Figure 18, the data sets associated with three DCBs are to be closed 


simultaneously. "See 
, CLOSE (TEXTDCB, , CONVDCB, , PRINTDCB) 

+ ~ CNOP 0,4 Align list to fullword 

- BAL 1,*+16 Load regl w/list addr 

+ DC AL1(0) Option byte 

+ DC AL3( TEXTDCB) DCB address 

+ DC AL1(0) Option byte 

+ DC AL3(CONVDCB ) DCB address 

+ DC AL1( 128) Option byte 

+ DC AL3(PRINTDCB) DCB address 

+ SVC 20 Issue close SVC 


Figure 18. Closing Three Data Sets Simultaneously 


Because no volume positioning operands are specified, the position indicated by 
the DD statement DISP parameter 1s used. 





Volume Positioning | 


At execution, the SVC 20 instruction passes control to the close routine, which 
ends the processing of the three data sets and returns the three DCBs to their 
original status. 
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Releasing Data Sets and Volumes 


You are offered the option of being able to release data sets and the volumes the 
data sets reside on when your task is no longer using them. If you are not 
sharing data sets, these data sets would otherwise remain unavailable for use by 
other tasks until the job step that opened them is terminated. 


There are two ways to code the CLOSE macro instruction that can result in 
releasing a data set and the volume on which it resides at the time the data set is 
closed: 


In conjunction with the FREE = CLOSE parameter of the DD statement, you 
can code: 


CLOSE (DCB1,DISP) or 
CLOSE (DCB1, REWIND) 


If you do not code FREE = CLOSE on the DD statement, you can code: 
CLOSE (DCB1,FREE) 


See JCL for information about how to use and code the FREE = CLOSE 
parameter of the DD statement. 


In either case, tape data sets and volumes are freed for use by another job step. 
Data sets on direct access devices will be freed and the volumes on which they 
reside will be freed if no other data sets on the volume are open. Additional 


information on volume disposition is provided in JCL. 


Data sets being temporarily closed (using CLOSE TYPE=T) cannot be released 
at the time the data set is closed. They will be released at the end of the job step. 


For additional information and coding restrictions on the CLOSE macro, see 
Data Administration: Macro Instruction Reference. 


End-of- Volume Processing 


The access methods pass control to the data management end-of-volume routine 
when any of the following conditions is detected: 


¢ Tapemark (input tape volume). 
e Filemark or end of last extent (input direct access volume). 


e End-of-data indicator (input device other than magnetic tape or direct access 
volume). An example of this would be the last card read on a card reader. 


e End of reel (output tape volume). 
e End of extent (output direct access volume). 


You may issue a force end-of-volume (FEOV) macro instruction before the 
end-of-volume condition 1s detected. 
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If the LABEL parameter of the associated DD statement shows standard labels, 
the end-of-volume routine checks or creates standard trailer labels. If SUL or 
AUL 1s specified, control is passed to the appropriate user label routine if it 1s 
specified in your exit list. | 


If multiple volume data sets are specified in your DD statement, automatic 
volume switching is accomplished by the end-of-volume routine. When an 
end-of-volume condition exists on an output data set, additional space is 
allocated as indicated in your DD statement. If no more volumes are specified or 
if more than specified are required, the storage is obtained from any available 
volume on a device of the same type. If no such volume is available, your job is 
terminated. 


Volume Positioning for Tapes 


When an end-of-volume condition is detected, the system positions the volume 
according to the disposition specified in the DD statement unless the volume 
disposition is specified in the OPEN macro instruction. Volume positioning 
instructions for a sequential data set on magnetic tape can be specified as LEAVE 
or REREAD. | 


LEAVE 
positions a labeled tape to the point following the tapemark that follows the 
data set trailer label group, and an unlabeled volume to the point following 
the tapemark that follows the last block of the data set. 


REREAD 
positions a labeled tape to the point preceding the data set header label 
group, and an unlabeled tape to the point preceding the first block of the 
data set. 


If the tape was last read backward: 


LEAVE 
positions a labeled tape to the point preceding the data set header label 
group, and an unlabeled tape to the point preceding the first block of the 
data set. 


REREAD 
positions a labeled tape to the point following the tapemark that follows the 
data set trailer label group, and an unlabeled tape to the point following the 
tapemark that follows the last block of the data set. 


If, however, you want to position the current volume according to the option 
specified in the DISP parameter of the DD statement, you code DISP in the 
OPEN macro instruction. 


DISP 
specifies that a tape volume 1s to be disposed of in the manner implied by 
the DD statement associated with the data set. Direct access volume 
positioning and disposition are not affected by this parameter of the OPEN 
macro instruction. There are several dispositions that can be specified in 
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( | the DISP parameter of the DD statement; DISP can be PASS, DELETE, 
‘ KEEP, CATLG, or UNCATLG. 


The resultant action at the tume an end-of-volume condition arises depends 
on (1) how many tape units are allocated to the data set and (2) how many 
volumes are specified for the data set in the DD statement. This is 
determined by the UNIT and VOLUME parameters of the DD statement 
associated with the data set. If the number of volumes is greater than the 
number of units allocated, the current volume will be rewound and 
unloaded. If the number of volumes is less than or equal to the number of 
units, the current volume is merely rewound. 


For magnetic tape volumes that are not being unloaded, positioning varies 
according to the direction of the last input operation and the existence of 
tape labels. 


If the tape was last read forward: 


LEAVE 
positions a labeled tape to the point following the tapemark that follows the 
data set trailer label group, and an unlabeled volume to the point following 
the tapemark that follows the last block of the data set. 


REREAD 
an positions a labeled tape to the point preceding the data set header label 
( group, and an unlabeled tape to the point preceding the first block of the 
. data set. 


If the tape was last read backward: 


LEAVE | 
positions a labeled tape to the point preceding the data set header label 
group, and an unlabeled tape to the point preceding the first block of the 
data set. 


REREAD | 7 
positions a labeled tape to the point following the tapemark that follows the 
data set trailer label group, and an unlabeled tape to the point following the 
tapemark that follows the last block of the data set. 


FEOV—Force End of Volume 


The FEOV macro instruction directs the operating system to start the © 
end-of-volume processing before the physical end of the current volume is 
reached. If another volume has been specified for the data set, volume switching 
takes place automatically. The volume positioning options REWIND and 
LEAVE are available. 


If an FEOV macro is issued for a spanned multivolume data set that is being read 
using QSAM, errors may occur when the next GET macro 1s issued. These 
errors are documented in “Spanned Format-VS Records (Sequential Access 
Method)” on page 19. 
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The FEOV macro instruction can only be used when you are using BSAM or (f 
QSAM. FEOV is ignored if issued for a SYSIN or SYSOUT data set. ed 


Device Independence 


The ability to request input/output operations without regard for the physical 
characteristics of the I/O devices makes it possible for you to write one program 
that will fulfill a variety of needs. Device independence may be useful for: 


e Accepting data from a number of recording devices, such as a disk pack, 7- or 
9-track magnetic tape, or unit-record equipment. This situation could arise 
when several types of data-acquisition devices are feeding a centralized 
complex. 


e Observing constraints imposed by the availability of input/output devices (for 
example, when devices on order have not been installed). 


e Assembling, testing, and debugging on one system configuration and 
processing on a different configuration. For example, an IBM 3330 Disk 
Storage drive can be used as a substitute for several magnetic tape units. 


Device independence is not difficult to achieve, but requires some programming 
considerations. See below. 


Programming Considerations Ne 


Each of three data set organizations—partitioned, indexed sequential, and 
direct—requires the use of a direct access device. Device independence is 
meaningful, then, only for a sequentially organized data set, that is, a data set in 
which one block of data follows another, thus allowing input or output to be on 
a magnetic tape drive, a direct access device, a card read/punch, a printer, or a 
spooled data set. 


Your program will be device independent if you do two things: 


¢ Omit all device-dependent macros and macro instruction parameters from 
your program. 


e Defer specifying any required device-dependent parameters until the program 
is ready for execution. That is, supply the parameters on your data definition 
(DD) statement or during the open exit routine. 


In examining the following list of macros, consider only the logical layout of your 
data record without regard for the type of device used. Also, consider that any 
reference to a direct access volume is to be treated as a reference to magnetic 
tape, that is, you must create a new data set rather than attempt to update. — 


OPEN 
Specify INPUT, OUTPUT, INOUT, OUTIN, OUTINX, or EXTEND. 
The parameters RDBACK and UPDAT are device dependent and cause an 
abnormal termination if directed to a device of the wrong type. 
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READ 
Specify forward reading (SF) only. 


WRITE 
Specify forward writing (SF) only; use only to create new records or modify 
existing records. 


PUTX 
Use only output mode. 


NOTE/POINT 
These macros are valid for both magnetic tape and direct access volumes. 


BSP 
This macro 1s valid for magnetic tape or direct access volumes. However, 
its use would be an attempt to perform device-dependent action. 


CNTRL/PRTOV 
These macros are device dependent. 


DCB Subparameters 


MACRE 
Specify R/W or G/P. Processing mode can also be indicated. 


DEVD 
Specify DA if any direct access device may be used. Magnetic tape and 
unit-record equipment DCBs will fit in the area provided during assembly. 
Specify unit-record devices only if you expect never to change to tape or 
direct access devices. 


KEYLEN 
Can be specified on the DD statement if necessary. 


RECFM, LRECL, BLKSIZE 
These can be specified in the DD statement. However, you must consider 
maximum record size for specific devices, and track overflow cannot be 
specified unless supported. Also, you must consider whether you expect to 
process XLRI records. 


DSORG 
Specify sequential organization (PS or PSU) to get the full DCB 
expansion. 


OPTCD 
This subparameter is device dependent; specify it in the DD statement. 


SYNAD 


Any device-dependent error checking is automatic. Generalize your routine 
so that no device-dependent information is required. 
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Chapter 6. Accessing Records in Data Sets 


Accessing Data with READ/WRITE 


The basic access technique provides the READ and WRITE macro instructions 
for transmitting data between virtual and auxiliary storage. This technique is 
used when you want to process records other than sequentially or when you do 
not want some or all of the automatic functions performed by the queued access 
technique. Although the system does not provide anticipatory buffering or 
synchronized scheduling, macro instructions are provided to help you program 
these operations. 


The READ and WRITE macro instructions process blocks, not records. Thus, 
blocking and unblocking of records are your responsibility. Buffers, allocated by 
either you or the operating system, are filled or emptied individually each time a 
READ or WRITE macro instruction is issued. Moreover, the READ and 
WRITE macro instructions only start input/output operations. To ensure that 
the operation is completed successfully, you must issue a CHECK macro 
instruction to test the data event control block (DECB). (The only exception to 
this is that, when the SYNAD or EODAD routine is entered, a CHECK macro 
instruction should not be issued for outstanding READ or WRITE requests.) 
The number of READ or WRITE macro instructions issued before a CHECK 
macro instruction is used should not exceed the specified number of channel 
programs (NCP). 


Grouping Related Control Blocks in a Paging Environment 


Related control blocks (the DCB and DECB) and data areas (buffers and key 
areas) should be coded so they assemble in the same area of your program. This 
will reduce the number of paging operations required to read from and write to 
your data set. 


Note: DCB, DECB, and buffers must reside below 16 megabytes. 

Using Overlapped I/O with BSAM 
When using BSAM with overlapped I/O (multiple I/O requests outstanding at 
one time), more than one DECB must be used. A different DECB should be 
specified for each channel program. For example, if you specify NCP = 3 in your 


DCB for the data set and you are reading records from the data set, you should 
code the following macros in your program: 
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READ—Read a Block 
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.READ DECB1,... 
.READ DECB2,... 
.READ DECB3,... 
.CHECK DECB1 
.CHECK DECB2 
.CHECK DECB3 


The READ macro retrieves a data block from an input data set and places it in a 
designated area of virtual storage. To allow overlap of the input operation with 
processing, the system returns control to your program before the read operation 
is completed. The DECB created for the read operation must be tested for 
successful completion before the record is processed or the DECB is reused. 


If an indexed sequential data set is being read, the block is brought into virtual 
storage and the address of the record 1s returned to you in the DECB. 


When you use the READ macro for BSAM to read a direct data set with 
spanned records and keys and you specify BFTEK = R in your DCB, the data 
management routines displace record segments after the first in a record by key 
length. Thus, you can expect the block descriptor word and the segment 
descriptor word at the same locations in your buffer or buffers, regardless of 
whether you read the first segment of a record, preceded in the buffer by its key, 
or a subsequent segment that does not have a key. This procedure is called offset 
reading. 


You can specify variations of the READ macro according to the organization of 
the data set being processed and the type of processing to be done by the system 


as follows: 


Sequential 


SF Read the data set sequentially. 


SB Read the data set backward (magnetic tape, format-F and format-U only). 
When RECEM = FBS, data sets with the last block truncated cannot be 
read backward. 

Indexed Sequential 


K Read the data set. 


KU _ Read for update. The system maintains the device address of the record; 
thus, when a WRITE macro returns the record, no index search is required. 


Direct 
D Use the direct access method. 


I Locate the block using a block identification. 


MVS/XA Data Administration Guide 





i . — 











K Locate the block using a key. 
F Provide device position feedback. 
Maintain exclusive control of the block. 


Provide next address feedback. 


Cc FF KK 


Next address can be a capacity record or logical record, whichever occurred 
first. 


WRITE—Write a Block 
The WRITE macro places a data block in an output data set from a designated 
area of virtual storage. The WRITE macro can also be used to return an 
updated record to a data set. To allow overlap of output operations with 
processing, the system returns control to your program before the write operation 
is completed. The DECB created for the write operation must be tested for 
successful completion before the DECB can be reused. For ISCII/ASCII tape 
data sets, do not issue more than one WRITE on the same record, because the 
WRITE macro instruction causes the data in the record area to be translated 


from EBCDIC to ISCII/ASCII. 

As with the READ macro, you can specify variations of the WRITE macro 

according to the organization of the data set and the type of processing to be 

done by the system as follows: 

Sequential 

SF Write the data set sequentially. 

Indexed Sequential 

K Write a block containing an updated record, or replace a record with a 
fixed, unblocked record having the same key. The record to be replaced 
need not have been read into virtual storage. 

KN _ Write a new record or change the length of a variable-length record. 

Direct 


SD Write a dummy fixed-length record. (BDAM load mode) 


SZ Write a capacity record (RO). The system supplies the data, writes the 
capacity record, and advances to the next track. (BDAM load mode) 


SFR Write the data set sequentially with next-address feedback. (BDAM load 
mode variable spanned) 


D Use the direct access method. 


I Search argument identifies a block. 
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K Search argument is a key. 
A Add a new block. 
F Provide record location data (feedback). 


xX Release exclusive control. 


CHECK—Test Completion of Read or Write Operation 


When processing a data set, you can test for completion of a READ or WRITE 
request by issuing a CHECK macro. The system tests for errors and exceptional 
conditions in the data event control block (DECB). Successive CHECK macros 
issued for the same data set must be issued in the same order as the associated 
READ and WRITE macros. 


The check routine passes control to the appropriate exit routines specified in the 
DCB for error analysis (SYNAD) or, for sequential data sets, end-of-data 
(EODAD). It also automatically starts the end-of-volume procedures (volume 
switching or extending output data sets). 


If you specify OPTCD = Q in the DCB, CHECK causes input data to be 
translated from ISCIH/ASCII to EBCDIC. 


WAIT—Wait for Completion of a Read or Write Operation 


When processing a data set, you can test for completion of any READ or 
WRITE request by issuing a WAIT macro. The input/output operation is 
synchronized with processing, but the DECB is not checked for errors or 
exceptional conditions, nor are end-of-volume procedures initiated. Your 
program must perform these operations. 


For BDAM and BISAM, a WAIT macro must be issued for each READ or 
WRITE macro if MACRF=C is not coded in the associated DCB. When 
MACRE = C 1s coded, and always for BsAM and BPAM, a CHECK macro 
must be issued for each READ or WRITE macro. Because the CHECK macro 
incorporates the function of the WAIT macro, a WAIT is normally redundant 
for those access methods. The ECBLIST form of the WAIT macro may be 
useful, though, in selecting which of several outstanding events should be checked 


first. | 


The WAIT macro can be used to await completion of multiple read and write 
operations. Each operation must then be checked or tested separately. Example: 
You have opened an input DCB for BSAM with NCP = 2, and an output DCB 
for BISAM with NCP = 1 and without specifying MACRF=C. You have issued 
two BSAM READ macros and one BISAM WRITE macro. You now issue the 
WAIT macro with ECBLIST pointing to the BISAM DECB and the first 
BSAM DECB. (Because BSAM requests are serialized, the first request must 
execute before the second.) When you regain control, you will inspect the 
DECBs to see which has completed (second bit on). If it was BISAM, you will 
issue another WRITE macro. If it was BSAM, you will issue a CHECK macro 
and then another READ macro. | 
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( Data Event Control Block (DECB) 


A data event control block is a 16- to 32-byte area reserved by each READ or 
WRITE macro. It contains the ECB, control information, and pointers to 
control blocks. The DCB ts described in Appendix A of Data Administration: 
Macro Instruction Reference. 


The DECB is examined by the check routine when the I/O operation is 
completed to determine if an uncorrectable error or exceptional condition exists. 
If it does, control is passed to your SYNAD routine. If you have no SYNAD 
routine, the task 1s abnormally terminated. 


Accessing Data with GET/PUT 


The queued access technique provides GET and PUT macros for transmitting 
data within virtual storage. These macro instructions cause automatic blocking 
and unblocking of the records stored and retrieved. Anticipatory (look-ahead) 
buffering and synchronization (overlap) of input and output operations with 
instruction stream processing are automatic features of the queued access method. 


Because the operating system controls buffer processing, you can use as many 
input/output (I/O) buffers as needed without reissuing GET or PUT macro 
- instructions to fill or empty buffers. Usually, more than one input block 1s in 
( storage at a time, so I/O operations do not delay record processing. 


Because the operating system synchronizes input/output with processing, you 
need not test for completion, errors, or exceptional conditions. After a GET or 
PUT macro 1s issued, control is not returned to your program until an input area 
is filled or an output area is available. Exits to error analysis (SYNAD) and 
end-of-volume or end-of-data (EODAD) routines are automatically taken when 
necessary. 


GET—Retrieve a Record 


The GET macro 1s used to obtain a record from an input data set. It operates in 
a logical sequential and device-independent manner. As required, the GET 
macro schedules the filling of input buffers, unblocks records, and directs input 
error recovery procedures. For sequential data sets, it also merges record 
segments into logical records. After all records have been processed and the GET 
macro detects an end-of-data indication, the system automatically checks labels 
on sequential data sets and passes control to your end-of-data (EODAD) routine. 
If an end-of-volume condition is detected for a sequential data set, the system 
provides automatic volume switching if the data set extends across several 
volumes or if concatenated data sets are being processed. If you specify 

OPTCD = Q in the DCB, GET causes input data to be translated from 
ISCII/ASCH to EBCDIC. 
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PUT—Write a Record | | | | 3 « * 
| | ey 

The PUT macro is used to write a record into an output data set. Like the GET 

macro, it operates in a logical sequential and device-independent manner. As 

required, the PUT macro blocks records, schedules the emptying of output 

buffers, and handles output error correction procedures. For sequential data sets, 

it also starts automatic volume switching and label creation, and also segments 

records for spanning. If you specify OPTCD= Q in the DCB, PUT causes 

output to be translated from EBCDIC to ISCII/ASCII. 


If the PUT macro is directed to a card punch or printer, the system automatically 
adjusts the number of records or record segments per block of format-F or 

format-V blocks to 1. Thus, you can specify a record length (LRECL) and block 
size (BLKSIZE) to provide an optimum block size if the records are iene ern | 
placed on magnetic tape or a direct access volume. : 


For spanned variable-length records, the block size must be equivalent to the 
length of one card or one print line. Record size may be greater than block size 
in this case. 


PUTX—Write an Updated Record 


The PUTX macro is used to update a data set or to create an output data set 
using records from an input data set as a base. PUTX updates, replaces, or 
inserts records from existing data sets but does not create records. © 


When you use the PUTX macro to update, each record is returned to the data 
set referred to by a previous locate mode GET macro instruction. The buffer 
containing the updated record is flagged and written back to the same location on 
the direct access storage device where it was read. The block is not written until 
a GET macro instruction is issued for the next buffer, except when a spanned 
record 1s to be updated. In that case, the block is wntten with the next GET 
macro. 7 


When the PUTX macro is used to create an output data set, you can add new 
records by using the PUT macro. As required, the PUTX macro blocks records, 
schedules the writing of output buffers, and handles output error correction 

- procedures. | 


Parallel Input Processing (QSAM Only) 


QSAM parallel input processing may be used to process two or more input data 
sets concurrently, such as sorting or merging several data sets at the same time. 
This eliminates the need for issuing a separate GET macro to each DCB 
processed. The get routine for parallel input processing selects a DCB with a 
ready record and then transfers control to the normal get routine. If there is no 
DCB with a ready record, a multiple WAIT macro is issued. 


Parallel input processing provides a logical input record from a queue of data sets 
with equal priority. The function supports QSAM with input processing, simple 
buffering, locate or move mode, and fixed-, variable-, or undefined-length records. 
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Spanned records, track-overflow records, dummy data sets, and SYSIN data sets 
are not supported. 


Parallel input processing can be interrupted at any time to retrieve records from a 
specific data set, or to issue control instructions to a specific data set. When the 
retrieval process has been completed, parallel input processing may be resumed. 


Data sets can be added to or deleted from the data set queue at any time. It 1s 
important to note, however, that, as each data set reaches an end-of-data 
condition, the data set must be removed from the queue with the CLOSE macro 
before a subsequent GET macro is issued for the queue; otherwise, the task may 
be ended abnormally. 


A request for parallel input processing is indicated by including the address of a 
parallel data access block (PDAB) in the DCB exit list. For additional 
information on the DCB exit list, see Chapter 7, “DCB Exit Routines” on 
page 75. | 


With the use of the PDAB macro, you can create and format a work area that 
identifies the maximum number of DCBs that can be processed at any one time. 
If you exceed the maximum number of entries indicated in the PDAB macro 
when adding a DCB to the queue with the OPEN macro, the data set will not be 
available for parallel input processing; however, it may be available for sequential 
processing. 


When issuing a parallel GET macro, register 1 must always point to a PDAB. 
You may load the register or let the GET macro do it for you. When control 1s 
returned to you, register 1 contains the address of a logical record from one of the 
data sets in the queue; registers 2 through 13 contain their original contents at the 
time the GET macro was issued; registers 14, 15, and 0 are changed. 


Through the PDAB, you can find the data set from which the record was 
retrieved. A fullword address in the PDAB (PDADCBEP) points to the address 
of the DCB. It should be noted that this pointer may be invalid from the time a 
CLOSE macro 1s issued to the issuing of the next parallel GET macro. 


In Figure 19 on page 68, not more than three data sets (MAXDCB = 3 in the 
PDAB operand) will be open for parallel processing at a time. If data definition 
statements and data sets are supplied, DATASET1, DATASET2, and 
DATASET3 will be opened for parallel input processing as specified in the input 
processing OPEN macro. Other attributes of each data set are QSAM 
(MACRF=G), simple buffering by default, locate or move mode (MACRF=L 
or M), fixed-length records (RECFM =F), and exit list entry for a PDAB 
(X’92’). Note that both locate and move modes may be used in the same data 
set queue. The mapping macros, DCBD and PDABD, are used to reference the 
DCBs and the PDAB respectively. 
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eo 
OPEN (DATASET1 » (INPUT) , DATASET2, (INPUT) , DATASET3, X 
(INPUT) , DATASET4 , (OUTPUT) ) 
™ DATASET 1+DCBQSWS - IHADCB ,DCBPOPEN: Opened for 
parallel processing 
BZ SEQRTN Branch on no to 
sequential routine 
T™ DATASET2+DCBQSWS - IHADCB , DCBPOPEN 
BZ SEQRTN 
™ DATASET3+DCBQSWS - IHADCB , DCBPOPEN 
BZ SEQRTN 
GETRTIN GET DCBQUEUE, BUFFERAD , TYPE=P 
LR 10,1 Save record pointer 
Record updated in place 
PUT DATASET4, (10) 
B GETRTIN 
EODRTN EQU). * Close DCB which just 
reached EODAD 
L 2 , DCBQUEVE+PDADCBEP - TIHAPDAB 
CLOSE ((2 | 
CLC ZEROS(2) , DCBQUEUE+PDANODCB-IHAPDAB Any DCBs left? 
BL GETRIN Branch if yes 
DATASET1 DCB DDNAME=DDNAME1,DSORG=PS,MACRF=GL, RECFM=FB, X 
LRECL=80 , EODAD=EODRTIN , EXLST=SET3XLST 
DATASET2 DCB  DDNAME=DDNAME2 , DSORG=PS , MACRF=GL, RECFM=FB, X . 
LRECL=80 , EODAD=EODRTN ,, EXLST=SET3XLST ‘ 
DATASET3 DCB DDNAME=DDNAME3 , DSORG=PS , MACRF=GMC , RECFM=FB, X y 
LRECL=80, EODAD=EODRTN, EXLST=SET3XLST 
DATASET4 DCB DDNAME=DDNAMEG , DSORG=PS, MACRF=PM, RECFM=FB, X 
LRECL=80 
DCBQUEUE PDAB MAXDCB=3 
SET3XLST DC OF" 0' »X' 92' , AL3(DCBQUEUE) 
ZEROS DC x' 0000' 
DCBD DSORG=QS 
PDABD 
Note: The number of bytes required for PDAB is equal to 24 + 8n, where n is the value of the keyword, 
MAXDCB. 
Figure 19. Parallel Processing of Three Data Sets 
Following the OPEN macro, tests are made to determine whether the DCBs were 
opened for parallel processing. If not, the sequential processing routine is given 
control. 
When one or more data sets are opened for parallel processing, the get routine 
retrieves a record, saves the pointer in register 10, processes the record, and writes 
it to DATASET4. This process continues until an end-of-data condition is 
detected on one of the input data sets; the end-of-data routine locates the 
completed input data set and removes it from the queue with the CLOSE macro. 
A test is then made to determine whether any data sets remain on the queue. oe 
Processing continues in this manner until the queue is empty. ( \ 
eq 
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Sharing Data Sets 


There are two conditions under which a data set on a direct access device can be 
shared by two or more tasks: 


e Two or more DCBs are opened and used concurrently by the tasks to refer 
to the same, shared data set (multiple DCBs). 


e Only one DCB is opened and used concurrently by multiple tasks in a single 
job step (a single, shared DCB). 


Job control language (JCL) statements and macros are provided in the operating 
system that help you ensure the integrity of the data sets you want to share 
among the tasks that process them. Figure 20 on page 70 and Figure 21 on 
page 71 show which JCL and macros you should use, depending on the access 
method your task is using and mode of access (input, output, or update). 


Figure 20 describes the macros, JCL, and processing procedures you should use 


if more than one DCB has been opened to the shared data set. The DCBs can 
be used by tasks in the same or different job steps. 
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MULTIPLE DCBs 


ACCESS METHOD 
ACCESS MODE 
BSAM, BPAM QSAM BDAM QISAM BISAM 
| Input —_—«| DISP = SHR |DISP = SHR |DISP = SHR|DISP = SHR |DISP = SHR 





No facility|No facility DISP = SHRINo facility |DISP = SHR 
Output and ENQ on 
Data Set 


DISP = SHR |DISP = SHR DISP = SHR; DISP = SHR DISP = SHR 
user must and Guarantee|BDAM will ftand ENQ on and EN@ on 
ENQ on discrete ENQ on 
Update block blocks block guarantee guarantee 
discrete discrete 
blocks blocks 


DISP = SHR: 
Each job step sharing an existing data set must code SHR as the subparameter of the DISP parameter 


on the DD statement for the shared data set to allow the steps to execute concurrently. For additional 
information about ensuring data set integrity, see /CL. If the tasks are in the same job step, 


DISP = SHR is not required. 





No facility: 
There are no facilities in the operating system for sharing a data set under these conditions. 


ENQ on data set: 
Besides coding DISP=SHR on the DD statement for the data set that is to be shared, each task must 


issue ENQ and DEQ macros naming the data set or block as the resource for which exclusive control 
is required. The ENQ must be issued before the GET (READ); the DEQ macro should be issued 
after the PUTX or CHECK macro that ends the operation. (For additional information on the use of 
ENQ and DEQ macros, see Supervisor Services and Macro Instructions.) 


Guarantee discrete blocks: 
When you are using the access methods that provide blocking and unblocking of records (QSAM, 


QISAM, and BISAM), it is necessary that every task updating the data set ensure that it is not 
updating a block that contains a record being updated by any other task. There are no facilities in the 
operating system for ensuring that discrete blocks are being processed by different tasks. 


ENQ on block: 
If you are updating a shared data set (specified by coding DISP=SHR on the DD statement) using 


BSAM or BPAM, your task and all other tasks must serialize processing of each block of records by 
issuing an ENQ macro before the READ macro and a DEQ macro after the CHECK macro that 
follows the WRITE macro you issued to update the record. If you are using BDAM, it provides for 
enqueuing on a block using the READ exclusive option that is requested by coding MACRF = X in 
the DCB and an X in the type operand of the READ and WRITE macros. (For an example of the 
use of the BDAM macros, see “Exclusive Control for Updating” on page 153.) 


Figure 20. JCL, Macro Instructions, and Procedures Required to Share a Data Set Using Multiple DCBs 


Figure 21 on page 71 describes the macros you can use to serialize processing of 
a shared data set when a single DCB is being shared by several tasks in a job 
step. The DISP=SHR specification on the DD statement is not required. 


Data sets can also be shared both ways at the same time. More than one DCB 


can be opened for a shared data set, while more than one task can be sharing one 
of the DCBs. Under this condition, the serialization techniques specified for 
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indexed sequential and direct data sets in Figure 20 satisfy the requirement. For 
sequential and partitioned data sets, the techniques specified in Figure 20 and 
Figure 21 must be used. 


More information on opening and closing data sets by more than one task is in 
“Opening and Closing a Data Set” on page 47. 


Shared Direct Access Storage Devices: At some installations, a direct access 
storage device is shared by two or more independent computing systems. Tasks 
executed on these systems can share data sets stored on the device. Careful 
planning should be exercised in accessing a shared data set or the same storage 
area on shared devices by multiple independent systems. Without proper 
intersystem communication, data integrity could be endangered. For details, see 
System Macros and Facilities. 


A SINGLE SHARED DCB 


ACCESS: METHOD | 
ACCESS | 
| MODE | BSAM, QSAM  BDAM | 
ROAM’ 
Create ; 


required 
pe T No action | ENQ and key| EN@ 
required | sequence : 


ENQ: 
When a data set is being shared by two or more tasks in the same job step 
(all that use the same DCB), each task processing the data set must issue an 
ENQ macro instruction on a predefined resource name before issuing the 
macro or macros that begin the input/output operation. Each task must 
also release exclusive control by issuing the DEQ macro at the next 
sequential instruction following the input/output macro. If, however, you 
are processing an indexed sequential data set sequentially using the SETL 
and ESETL macros, you must issue the ENQ macro before the SETL 
macro and the DEQ macro after the ESETL macro. Note also that if two 
tasks are writing different members of a partitioned data set, each task 
should issue the ENQ macro before the FIND macro and issue the DEQ 
macro after the STOW macro that completes processing of the member. 
Additional reference information on the ENQ and DEQ macros is 
presented in Supervisor Services and Macro Instructions. For an example of 
the use of ENQ and DEQ macros with BISAM, see Figure 53 on 
page 152. 





Figure 21 (Part I of 2). Macro Instructions and Procedures Required to Share a Data 
Set Using a Single DCB 
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No action required: - 
See “Sharing Direct Data Sets” on page 157. 


ENQ on 1 block: 
When updating a shared BDAM data set, every task must use the BDAM 
exclusive control option that is requested by coding MACRF = X in the 
DCB macro and an X in the type operand of the READ and WRITE 
macro instructions. See “Exclusive Control for Updating” on page 153 for 
an example of the use of BDAM macros. Note that all tasks sharing a data 
set must share subpool 0 (see the ATTACH macro description in 
Supervisor Services and Macro Instructions). 


Key sequence: 
Tasks sharing a QISAM load mode DCB must ensure that the records to 
be written are presented in ascending key sequence; otherwise, a sequence 
check will result in (1) control being passed to the SYNAD routine 
identified by the DCB, or (2) if there is no SYNAD routine, termination of 
the task. 


Figure 21 (Part 2 of 2). Macro Instructions and Procedures Required to Share a Data 
Set Using a Single DCB 


Analyzing I/O Errors -_ 


The basic and queued access techniques both provide special macro instructions 
for analyzing input/output errors. These macro instructions can be used in 
SYNAD routines or in error analysis routines. 


SYNADAF—Perform SYNAD Analysis F unction 


The SYNADAF macro analyzes the status, sense, and exceptional condition code 
data that is available to your error analysis routine. It produces an error message 
that your routine can write into any appropriate data set. The message 1s in the 
form of an unblocked variable-length record, but you can wnite it as a 
fixed-length record by omitting the block length and record length fields that 
precede the message text. 


The text of the message is 120 characters long, and begins with a field of either 36 
or 42 blanks; you can use the blank field to add your own remarks to the 
message. Following is a typical message with the blank field omitted: 


,» TESTJOBb, STEP2bbb, 283, TA, MASTERbb, READb, DATA CHECKbbbbb, 
0000015, BSAM 


Note: In the above example, a b indicates a blank. 


This message shows that a data check occurred during reading of the 15th block 
of a data set. The data set was identified by a DD statement named MASTER, 
and was on a magnetic tape volume on unit 283. The name of the job was 
TESTJOB; the name of the job step was STEP2. 
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If the error analysis routine is entered because of an input error, the first 6 bytes 
of the message (bytes 8 to 13) contain binary information. If no data was 
transmitted or if the access method is QISAM, the first 6 bytes are blanks or 
binary zeros. If the error did not prevent data transmission, the first 6 bytes 
contain the address of the input buffer and the number of bytes read. You can 
use this information to process records from the block; for example, you might 
print each record after printing the error message. Before printing the message, 
however, you should replace this binary information with EBCDIC characters. 


The SYNADAF macro provides its own save area and makes this area available 
to your error analysis routine. When used at the entry point of a SYNAD 
routine, it fulfills the routine’s responsibility for providing a save area. 


SYNADRLS—Release SYNADAF Message and Save Areas 


The SYNADRLS macro releases the message and save areas provided by the 
SYNADAF macro. You must issue this macro instruction before returning from 
the error analysis routine. 


ATLAS—Perform Alternate Track Location Assignment 


The ATLAS macro lets your program recover from permanent input/output 
errors when processing a data set in direct access storage. After a data check, or 
in certain missing-address-marker conditions, you can issue ATLAS to assign an 
alternate track to replace the error track or transfer data from the error track to 
the alternate track. 


The use of this macro requires a knowledge of channel programming. A detailed 
description of the macro instruction and its use is included in System-Data 
Administration. | 


If you do not use the ATLAS macro, you can use the IEHATLAS utility 
program or the Device Support Facilities program to do the same function. The 
principal difference between ATLAS and the IEHATLAS utility program is that 
the latter provides error recovery only after your own program has been 
completed. (For a detailed description of IEHATLAS, see Uiilities.) The 
INSPECT command for the Device Support Facilities program can assign 
alternate tracks. (See Device Support Facilities User's Guide and Reference.) 
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When Available Where Specified 


End-of-data-set When no more sequential records or blocks EODAD operand 
are available | 


After an uncorrectable input/output error SYNAD operand 


Block count After unequal block count comparison by EXLST operand and exit list 
end-of-volume routine 

DCB abend When an abend condition occurs in OPEN, EXLST operand and exit list 
CLOSE, or EOV routine 


DCB open When opening a data set EXLST operand and exit list 


Defer input trailer | When end-of-data is reached EXLST operand and exit list 
label 
When end-of-data is reached EXLST operand and exit list 


End-of-volume When changing volumes EXLST operand and exit list 


FCB image When opening a data set or issuing a EXLST operand and exit list 
SETPRT macro 

I/O error When an I/O error has occurred EXLST operand and exit list 

processing exit 


Figure 22 (Part 1 of 2). 


Defer nonstandard 
input trailer label 








Chapter 7. DCB Exit Routines 


The DCB macro can be used to identify the location of: 

e A routine that performs end-of-data procedures 

e A routine that supplements the operating system’s error recovery routine 

e A list that contains addresses of special exit routines 

The exit addresses can be specified in the DCB macro or you can complete the 
DCB fields before opening the data set. Figure 22 summarizes the exits that you 
can specify either explicitly in the DCB, or implicitly by specifying the address of 
an exit list in the DCB. 

Because OPEN/CLOSE/EOV enqueues on SYSZTIOT, functions that require 


SYSZTIOT cannot be executed in the OPEN/CLOSE/EOV exit routines. Some 
of these functions are LOCATE, OBTAIN, SCRATCH, and CATALOG. 








Data Management Exit Routines 
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When Available Where Specified 


JFCB When opening a data set with OPEN EXLST operand and exit list 
_ | TYPE=J and RDJFCB 


JFCBE _ | When opening a data set for the 3800 EXLST operand and exit list 
Nonspecific tape When a scratch tape is requested during EXLST operand and exit list 
volume mount OPEN or EOV routines 

QSAM parallel When opening a data set for QSAM EXLST operand and exit list 
input processing 


Standard user When opening, closing, or reaching the end of | EXLST operand and exit list 
label (physical a data set, and when changing volumes 
sequential or 
direct 

organization) 


User totaling area | When an I/O operation is scheduled and user | EXLST operand and exit list 

totaling has been requested | 
Volume security/ When a scratch tape is requested during EXLST operand and exit list 
verification OPEN or EOV routines : | 


Figure 22 (Part 2 of 2). Data Management Exit Routines 







































End-of-Data-Set Exit Routine (EODAD) 


The EODAD parameter of the DCB macro specifies the address of your 
end-of-data-set routine, which may perform any final processing on an input data 
set. This routine is entered when an FEOV macro is issued or when a CHECK 
or GET macro is issued and there are no more records or blocks to be retrieved. 
(On a READ request, this routine is entered when you issue a CHECK macro to 
check for completion of the read operation. For a BSAM data set that is opened 
for UPDAT, this routine is entered at the end of each volume. (This allows you 
to issue WRITE macros before an FEOV macro is issued.) 


The EODAD routine is not a subroutine, but rather a continuation of the 
routine that issued the CHECK, GET, or FEOV macro. After it 1s in your 
EODAD routine, you can continue normal processing, such as repositioning and 
resuming processing of the data set, closing the data set, or processing another 
data set. 


For BSAM, you must first reposition the data set that reached end-of-data if you 
want to issue a BSP, READ, or WRITE macro. You can reposition your data 
set by issuing a CLOSE TYPE=T macro instruction. If a READ macro is 
issued before the data set is repositioned, unpredictable results will occur. 


For BPAM, you may reposition the data set by issuing a FIND or POINT 
macro. (CLOSE TYPE=T with BPAM results in no operation performed.) 


For QISAM, you can continue processing the input data set that reached 
end-of-data by first issuing an ESETL macro to end the sequential retrieval, then 
issuing a SETL macro to set the lower limit of sequential retrieval. You can then 
issue GET macros to the data set. 
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Your task will be abnormally ended under either of the following conditions: 


e No exit routine 1s provided. 


¢ A GET macro is issued in the EODAD routine to the DCB that caused this 
routine to be entered (unless the access method is QISAM). 


When control is passed to the EODAD routine, the registers contain the 
following information: 


Register Contents 


0-1 Reserved 

2-13 Contents before execution of CHECK, GET, or FEOV macro 
instruction 

14 Address of the instruction after the last issued GET, CHECK, or 
FEOV macro 

15 Reserved 


Synchronous Error Routine Exit (GSYNAD) 


The SYNAD parameter of the DCB macro specifies the address of an error 
routine that is to be given control when an input/output error occurs. This 
routine can be used to analyze exceptional conditions or uncorrectable errors. 
The block being read or written can be accepted or skipped, or processing can be 
terminated. 


If an input/output error occurs during data transmission, standard error recovery 
procedures, provided by the operating system, try to correct the error before 
returning control to your program. An uncorrectable error usually causes an 
abnormal termination of the task. However, if you specify in the DCB macro 
the address of an error analysis routine (called a SY NAD routine), the routine 1s 
given control if an uncorrectable error 1s detected. 


You can write a SYNAD routine to determine the cause and type of error that 
occurred by examining: 


e The contents of the general registers 


e The data event control block (discussed in ‘Accessing Data with 
READ/WRITE” on page 61) 


e The exceptional condition code 
e The standard status and sense indicators 
You can use the SYNADAF macro to perform this analysis automatically. This 


macro produces an error message that can be printed by a later PUT or WRITE 
macro. 
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After completing the analysis, you can return control to the operating system or f 
close the data set. If you close the data set, note that you may not use the 
temporary close (CLOSE TYPE=T) option in the SYNAD routine. To 
continue processing the same data set, you must first return control to the control 
program by a RETURN macro. The control program then transfers control to 
your processing program, subject to the conditions described below. Never 
attempt to reread or rewrite the record, because the system has already attempted 
to recover from the error. 


When you are using GET and PUT to process a sequential data set, the 
operating system provides three automatic error options (EROPT) to be used if 
there is no SYNAD routine or if you want to return control to your program 
from the SYNAD routine: 


e ACC-—accept the erroneous block 
e SKP —skip the erroneous block 
¢ ABE-—abnormally terminate the task 


These options are applicable only to data errors, because control errors result in 
abnormal termination of the task. Data errors affect only the validity of a block 
of data. Control errors affect information or operations necessary for continued 
processing of the data set. These options are not applicable to output errors, 
except output errors on the printer. If the EROPT and SYNAD fields are not 
completed, ABE is assumed. 


If a control error or a physical I/O error is encountered for a SYSIN or SYSOUT 
dataset, the EROPT options will be ignored and the task will be abnormally 
terminated. 


You should not use the FEOV macro against the data set for which the SYNAD 
routine was entered, within the SYNAD routine. 


Because EROPT applies to a physical block of data, and not to a logical record, 
use of SKP or ACC may result in incorrect assembly of spanned records. 


When you use READ and WRITE macros, errors are detected when you issue a 
CHECK macro. If you are processing a direct or sequential data set and you 
return to the control program from your SYNAD routine, the operating system 
assumes that you have accepted the bad record. If you are creating a direct data 
set and you returm to the control program from your SYNAD routine, your task 
is abnormally terminated. In the case of processing a direct data set, the return 
should be made to the control program via register 14 to make a control block 
(the IOB) available for reuse in a later READ or WRITE macro. 


For a description of the register contents on entry to your SYNAD routine, see 
the tables in Data Administration: Macro Instruction Reference. The tables there 
describe register contents for programs using QISAM, BISAM, BDAM, BPAM, 
BSAM, and QSAM. 

Your SYNAD routine can end by branching to another routine in your program, “oY 
such as a routine that closes the data set. It can also end by returning control to 
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the control program, which then returns control to the next sequential instruction 
(after the macro) in your program. Control is not returned to the application if it 
returns to the system after a control error or physical I/O error for a SYSIN or 
SYSOUT data set. In this case, the task is abnormally terminated. If your 
routine returns control, the conventions for saving and restoring register contents 
are as follows: 


e The SYNAD routine must preserve the contents of registers 13 and 14. If 
required by the logic of your program, the routine must also preserve the 
contents of registers 2 through 12. On return to your program, the contents 
of registers 2 through 12 will be the same as on return to the control program 
from the SYNAD routine. 


¢ The SYNAD routine must not use the save area whose address is in register 
13, because this area is used by the control program. If the routine saves and 
restores register contents, it must provide its own save area. 


e Ifthe SYNAD routine calls another routine or issues supervisor or data 
management macros, it must provide its own save area or issue a SY NADARP 
macro. The SYNADAF macro provides a save area for its own use, and 
then makes this area available to the SYNAD routine. Such a save area 
must be removed from the save area chain by aSYNADRLS macro before 
control is returned to the control program. 


If the error analysis routine receives control from the close routine when indexed 
sequential data sets are being created (the DCB is opened for QISAM load 
mode), bit 3 of the IOBFLAGS field in the load mode buffer control table 
(IOBBCT) is set to 1. The DCBWKPT6 field in the DCB contains an address 
of a list of work area pointers (ISLVPTRS). The pointer to the IOBBCT is at 
offset 8 in this list as shown in the following diagram: 


Work Area 















DCB . 
Pointers 
{(ISLVPTRS) \OBBCT 
0} ae : = rm : —7 
an6 DCBWKPT6 : A (IOBBCT) I 





lIOBFLAGS 





If the error analysis routine receives control from the CLOSE routine when 
indexed sequential data sets are being processed using QISAM scan mode, bit 2 
of the DCB field DCBEXCD2 is set to 1. 
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Exit List (EXLST) 
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The EXLST parameter of the DCB macro specifies the address of a list that 
contains the addresses of special processing routines, a forms control buffer 
(FCB) image, or a user totaling area. An exit list must be created if user label, 
data control block, end-of-volume, block count, JECBE, or DCB abend exits are 
used, or if a PDAB macro or FCB image 1s defined in the processing program. 


The exit list is built of 4-byte entries that must be aligned on fullword 


boundaries. Each exit list entry 1s identified by a code in the high-order byte, and 
the address of the routine, image, or area is specified in the 3 low-order bytes. 


Codes and addresses for the exit list entries are shown in Figure 23. 


Hex 
Code 3-Byte Address—Purpose 


Ignore the entry; it is not 
active. 


Process a user input 
header label. 

Create a user output 
header label. 

Process a user input trailer 
label. 

Create a user output 
trailer label. 

Take a data control block 
exit. 


Take an end-of-volume 
exit. 


07 JFCB address for 
RDJFCB and OPEN ; 
TYPE=J SVCs. | 




















Entry Type 











End-of-volume exit 
JECBexit 


User totaling area 
Block count exit 


Defer input trailer label 


[Reserved 


Address of beginning of 
user’s totaling area. | 


Take a 
block-count-unequal exit. 


Defer processing of a user 
input trailer label from 
end-of-data until closing. 






Defer processing a 
nonstandard input trailer 
label on magnetic tape 
unit from end-of-data 
until closing (no exit 
routine address). 


Defer nonstandard input 
trailer label 










F igure 23 (Part 1 of 2). DCB Exit List Format and Contents 
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Hex 
Entry Type Code 3-Byte Address—Purpose 
0E-0F 
FCB image Define an FCB image. 


DCB abend exit Examine the abend 
| condition and select one 
of several options. 


Address of the PDAB for 
which this DCB 1s a 
member. 


[Reserved Cid 


Take an exit during 
OPEN to allow user to 

examine JCL= specified 
setup requirements for a 
3800 printer. 















10 
QSAM parallel input aa 
Sa 


JECBE exit 


[is [Reserved 


OPEN/EOV nonspecific Option to specify a tape 
| tape volume mount volume serial number. 
















10 
il 
12 

5 
16 
17 


OPEN/EOV volume 18 Verify a tape volume and 
security/verification some security checks. 


CS*dSTF[ Reserved. 


Last entry 7 Treat this entry as the last 


entry in the list. This 
Figure 23 (Part 2 of 2). DCB Exit List Format and Contents 






code can be specified with 
any of the above but must 
always be specified with 

the last entry exit routine. 







You can activate or deactivate any entry in the list by placing the required code 
in the high-order byte. Care must be taken, however, not to destroy the last 
entry indication. The operating system routines scan the list from top to bottom, 
and the first active entry found with the proper code is selected. | 


You can shorten the list during execution by setting the high-order bit to 1, and 
extend it by setting the high-order bit to 0. 
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When control is passed to an exit routine, the registers contain the following a 
information: en 
Register Contents 
0 Variable; see exit routine description. 
] The 3 low-order bytes contain the address of the DCB currently being 
processed, except when the user-label exits (X’01’-X‘04’), user totaling 
exit (X’0A’), DCB abend exit (X’11’), nonspecific tape volume mount 
exit (X’17’), or the tape volume security/verification exit (X‘18’) is 
taken, when register 1 contains the address of a parameter list. The 
contents of the parameter list are described in the explanation of each 
exit routine. 
2-13 Contents before execution of the macro. 
14 Return address (must not be altered by the exit routine). 
15 Address of exit routine entry point. 
The conventions for saving and restoring register contents are as follows: 
e The exit routine must preserve the contents of register 14. It need not 
preserve the contents of other registers. The control program restores the 
contents of registers 2 to 13 before returning control to your program. _ 


Se ig 
oa ea 
wn 


e The exit routine must not use the save area whose address is in register 13, 
because this area is used by the control program. If the exit routine calls 
another routine or issues supervisor or data management macros, it must 
provide the address of a new save area in register 13. 


¢ The DCBOFUEX bit in the DCBOFLGS is set to zero when a user exit 1s 
taken. This restricts the use of certain macros (for example, CLOSE) in an | 
exit routine. | : 


Standard User Label Exit | 


When you create a data set with physical sequential or direct organization, you 
can provide routines to create your own data set labels. You can also provide 
routines to verify these labels when you use the data set as input. Each label is 
80 characters long, with the first 4 characters UHL1,UHL2,..., UHL8 for a header 
label or UTL1,UTL2,..., UTLS8 for a trailer label. User labels are not allowed on 
indexed sequential data sets. | | 


The physical location of the labels on the data set depends on the data set 
organization. For direct (BDAM) data sets, user labels are placed on a separate 
user label track in the first volume. User label exits are taken only during 
execution of the OPEN and CLOSE routines. Thus you may create or examine 
as many as eight user header labels only during execution of OPEN and as many a 
as eight trailer labels only during execution of CLOSE. Because the trailer labels a 
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are on the same track as the header labels, the first volume of the data set must 
be mounted when the data set is closed. 


For physical sequential (BSAM or QSAM) data sets, you may create or examine 
as many as eight header labels and eight trailer labels on each volume of the data 
set. For ASCII tape data sets, you may create an unlimited number of user 
header and trailer labels. The user label exits are taken during OPEN, close, and 
end-of-volume processing. 


To create or verify labels, you must specify the addresses of your label exit 
routines in an exit list as shown in Figure 23 on page 80. Thus you may have 
separate routines for creating or verifying header and trailer label groups. Care 
must be taken if a magnetic tape is read backward, because the trailer label group 
is processed as header labels and the header label group is processed as trailer 
labels. 


When your routine receives control, the contents of register 0 are unpredictable. 
Register 1 contains the address of a parameter list. The contents of registers 2 to 
13 are the same as when the macro instruction was issued. However, if your 
program does not issue the CLOSE macro, or abnormally ends before issuing 
CLOSE, the CLOSE macro will be issued by the control program, with 
control-program information in these registers. 


The parameter list pointed to by register 1 is a 16-byte area aligned on a fullword 
boundary. Figure 24 shows the contents of the area. 






0 
oo Address of 80-byte label Batick area 
4 
Address of DCB being processed 





Address of user totaling image area 





an 
Gffff 


Figure 24. Parameter List Passed to User Label Exit Routine 


The first address in the parameter list points to an 80-byte label buffer area. For 
input, the control program reads a user label into this area before passing control 
to the label routine. For output, the user label exit routine builds labels 1n this 
area and returns to the control program, which writes the label. When an input 
trailer label routine receives control, the EOF flag (high-order byte of the second 
entry in the parameter list) is set as follows: 


Bit O O: Entered at end-of-volume 
Bit O 1: Entered at end-of-file 
Bits 1-7: Reserved 


When a user label exit routine receives control after an uncorrectable I/O error 
has occurred, the third entry of the parameter list contains the address of the 
standard status information. The error flag (high-order byte of the third entry in 
the parameter list) is set as follows: 
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Bit 0 = 1: Uncorrectable I/O error 
Bit 1 = 1: Error occurred during writing of updated label 
Bits 2-7: Reserved 


The fourth entry in the parameter list is the address of the user totaling image 
area. This image area is the entry in the user totaling save area that corresponds 
to the last record physically written on the volume. (The image area is discussed 
further under “User Totaling (BSAM and QSAM only)” on page 86.) 


Each routine must create or verify one label of a header or trailer label group, 
place a return code in register 15, and return control to the operating system. 
The operating system responds to the return code as shown in Figure 25. 


You can create user labels only for data sets on magnetic tape volumes with IBM 
standard labels or ISO/ANSI/FIPS labels and for data sets on direct access 
volumes. When you specify both user labels and IBM standard labels in a DD 
statement by specifying LABEL=(,SUL) and there is an active entry in the exit 
list, a label exit is always taken. Thus, a label exit is taken even when an input 
data set does not contain user labels, or when no user label track has been 
allocated for writing labels on a direct access volume. In either case, the 
appropriate exit routine is entered with the buffer area address parameter set to 0. 
On return from the exit routine, normal processing is resumed; no return code is 
necessary. 


Routine Type Return Code System Response 
Input header or 0 (X00) Normal processing is resumed. If 
trailer label there are any remaining labels in the 
| label group, they are ignored. 
4 (X’04’) The next user label is read into the 


label buffer area and control is 
returned to the exit routine. If there 
are no more labels in the label 
group, normal processing is resumed. 

8! (X’08’) The label is written from the label 
buffer area and normal processing is 
resumed. 

12! (X’0C’/) The label is written from the label 
area, the next label is read into the 
label buffer area, and control is 
returned to the label processing 
routine. If there are no more labels, 
processing is resumed. 

Output header or 0 (X’00’) Normal processing is resumed; no 
trailer label label is written from the label buffer 
area. | 

4 (X'04’/) User label is written from the label 
buffer area. Normal processing is 
resumed. 


Figure 25 (Part 1 of 2). System Response to a User Label Exit Routine Return Code 
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Routine Type Return Code System Response 


8 (X’08’) User label is written from the label 
buffer area. If fewer than eight labels 
have been created, control is 
returned to the exit routine, which 
then creates the next label. If eight 
labels have been created, normal 
processing 1s resumed. 


Figure 25 (Part 2 of 2). System Response to a User Label Exit Routine Return Code 


Note to Figure 25 


1 


Your input label routines can return these codes only when you are 
processing a physical sequential data set opened for UPDAT or a direct data 
set opened for OUTPUT or UPDAT. These return codes allow you to 
verify the existing labels, update them if necessary, then request that the 
system write the updated labels. 


Label exits are not taken for system output (SYSOUT) data sets, or for data sets 
on volumes that do not have standard labels. For other data sets, exits are taken 
as follows: 


When an input data set is opened, the input header label exit 01 1s taken. If 
the data set 1s on tape being opened for RDBACK, user trailer labels will be 
processed. 


When an output data set is opened, the output header label exit 02 is taken. 
However, if the data set already exists and DISP = MOD is coded in the DD 
statement, the input trailer label exit 03 1s taken to process any existing trailer 
labels. If the input trailer label exit 03 does not exist, then the deferred input 
trailer label exit OC is taken if it exists; otherwise, no label exit is taken. For 
tape, these trailer labels will be overwritten by the new output data or by 
EOV or close processing when writing new standard trailer labels. For direct 
access devices, these trailer labels will still exist unless rewritten by EOV or 
close processing in an output trailer label exit. 


When an input data set reaches end-of-volume, the input trailer label exit 03 
is taken. If the data set is on tape opened for RDBACK, header labels will 
be processed. The input trailer label exit 03 is not taken if you issue an 
FEOV macro. If a defer input trailer label exit OC is present, and an input 
trailer label exit 03 is not present, the OC exit is taken. After switching 
volumes, the input header label exit 01 is taken. If the data set is on tape 
opened for RDBACK, trailer labels will be processed. 


When an output data set reaches end-of-volume, the output trailer label exit 
04 1s taken. After switching volumes, output header label exit 02 1s taken. 


When an input data set reaches end-of-data, the input trailer label exit 03 1s 


taken before the EODAD exit, unless the DCB exit list contains a defer input 
trailer label exit OC. 
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e When an input data set is closed, no exit is taken unless the data set was 
previously read to end-of-data and the defer input trailer label exit OC is 
present. If so, the defer input trailer label exit OC is taken to process trailer 
labels, or if the tape is opened for RDBACK, header labels. 


¢ When an output data set is closed, the output trailer label exit 04 is taken. 


To process records in reverse order, a data set on magnetic tape can be read 
backward. When you read backward, header label exits are taken to process 
trailer labels, and trailer label exits are taken to process header labels. The system 
presents labels from a label group in ascending order by label number, which is 
the order in which the labels were created. If necessary, an exit routine can 
determine label type (UHL or UTL) and number by examining the first four 
characters of each label. Tapes with IBM standard labels and direct access 
devices can have as many as eight user labels. Tapes with ISO/ANSI/FIPS labels 
can have an unlimited number of user labels. 


If an uncorrectable error occurs during reading or writing of a user label, the 
system passes control to the appropriate exit routine, with the third word of the 
parameter list flagged and pointing to status information. 


After an input error, the exit routine must return control with an appropriate 
return code (0 or 4). No return code is required after an output error. If an 
output error occurs while the system is opening a data set, the data set is not 
opened (DCB is flagged) and control is returned to your program. If an output 
error occurs at any other time, the system attempts to resume normal processing. 


User Totaling (BSAM and QSAM only) 


When creating or processing a data set with user labels, you may develop control 
totals for each volume of the data set and store this information in your user 
labels. For example, a control total that was accumulated as the data set was 
created can be stored in your user label and later compared with a total 
accumulated during processing of the volume. User totaling helps you by 
synchronizing the control data you create with records physically written on a 
volume. For an output data set without user labels, you can also develop a 
control total that will be available to your end-of-volume routine. 


To request user totaling, you must specify OPTCD=T in the DCB macro 
instruction or in the DCB parameter of the DD statement. The area in which 
you collect the control data (the user totaling area) must be identified to the 
control program by an entry of hexadecimal 0A in the DCB exit list. 
OPTCD=T cannot be specified for SYSIN or SYSOUT data sets. 


The user totaling area, an area in storage that you provide, must begin on a 
halfword boundary and be large enough to contain your accumulated data plus a 
2-byte length field. The length field must be the first 2 bytes of the area and 
specify the length of the complete area. A data set for which you have specified 
user totaling (OPTCD=T) will not be opened if either the totaling area length or 
the address in the exit list is 0, or if there is no X’0A’ entry in the exit list. 
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The control program establishes a user totaling save area, where the control 
program preserves an image of your totaling area, when an I/O operation 1s 
scheduled. When the output user label exits are taken, the address of the save 
area entry (user totaling image area) corresponding to the last record physically 
written on a volume is passed to you in the fourth entry of the user label 
parameter list. (This parameter list is described in “Standard User Label Exit” on 
page 82.) When an end-of-volume exit is taken for an output data set and user 
totaling has been specified, the address of the user totaling image area is in 
register 0. 


When using user totaling for an output data set, that is, when creating the data 
set, you must update your control data in your totaling area before issuing a 
PUT or a WRITE macro. The control program places an image of your totaling 
area in the user totaling save area when an J/O operation is scheduled. A pointer 
to the save area entry (user totaling image area) corresponding to the last record 
physically wntten on the volume, is passed to you in your label processing 
routine. Thus you can include the control total in your user labels. When 
subsequently using this data set for input, you can collect the same information 
as you read each record and compare this total with the one previously stored in 
the user trailer label. If you have stored the total from the preceding volume in 
the user header label of the current volume, you can process each volume of a 
multivolume data set independently and still maintain this system of control. 


When variable-length records are specified with the totaling function for user 
labels, special considerations are necessary. Because the control program 
determines whether a variable-length record will fit in a buffer after a PUT or a 
WRITE has been issued, the total you have accumulated may include one more 
record than is really written on the volume. For variable-length spanned records, 
the accumulated total will include the control data from the volume-spanning 
record although only a segment of the record is on that volume. However, when 
you process such a data set, the volume-spanning record or the first record on the 
next volume will not be available to you until after the volume switch and user 
label processing are completed. Thus the totaling information in the user label 
may not agree with that developed during processing of the volume. 


One way you can resolve this situation is to maintain, when you are creating a 
data set, contro] data pertaining to each of the last two records and include both 
totals in your user labels. Then the total related to the last complete record on 
the volume and the volume-spanning record or the first record on the next 
volume would be available to your user label routines. During subsequent 
processing of the data set, your user label routines can determine if there is 
agreement between the generated information and one of the two totals 
previously saved. : | 


When the totaling function for user labels is selected with DASD devices and 
secondary space is specified, the total accumulated may be one less than the 
actual written. - | 
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Data Control Block Open Exit 


You can specify in an exit list the address of a routine that completes or modifies 
a DCB and does any additional processing required before the data set is 
completely open. The routine is entered during the opening process after the 
JFCB has been used to supply information for the DCB. The routine can 
determine data set characteristics by examining fields completed from the data set 
labels. When your DCB exit routine receives control, the 3 low-order bytes of 
register 1 will contain the address of the DCB currently being processed. 


As with label processing routines, the contents of register 14 must be preserved 
and restored if any macros are used in the routine. Control is returned to the 
operating system by a RETURN macro; no return code is required. 


This exit is mutually exclusive with the JFCBE exit. If you need both the 
JFCBE and data control block OPEN exits, you must use the JFCBE exit to 
pass control to your routines. 


The DCB OPEN exit is intended for modifying or updating the DCB. System 
functions should not be attempted in this exit prior to returning to OPEN 
processing; in particular, dynamic allocation, OPEN, CLOSE, EOV, and 
DADSM functions should not be invoked because of an existing OPEN enqueue 
on the SYSZTIOT resources. 


Open/EOV Nonspecific Tape Volume Mount Exit 


This user exit gives you the option of identifying a specific tape volume to be 
requested in place of a nonspecific (scratch) tape volume. A X’17’ in the DCB 
exit list (EXLST) activates this exit. (See “Exit List (EXLST)” on page 80 for 
more information about EXLST.) This exit, which supports only IBM standard 
labeled tapes, was designed to be used with the Open/EOV volume security and 
verification user exit. .However, this exit can be used by itself. 


Open or end-of-volume (EOV) calls this exit when either must issue mount 
message IECS01A or EICSO1E to request a scratch tape volume. Open issues the 
mount message if you specify the DEFER parameter with the UNIT option, and 
you either didn’t specify a volume serial number in the DD statement or you 
specified "VOL=SER=SCRTCH'". EOV always calls this exit for a scratch 
tape volume request. | 


This user exit gets control in the key and state of the program that issued the 
OPEN or EOV, and no locks are held. After you are in control, you must 
provide a return code in register 15. 
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OENTID 
OENTFLG 

OENTOEOV 
OENTNTRY 
OENTOPTN 
OENTMASK 
OENTRSVD 
OENTDCBA 
OENTVSRA 
OENTJFCB 
OENTLENG 
OENTREGS 
OENTAREA 


+Hteteeteetetete 


EQU 





Return Code Meaning 


00 (X’00’) Continue with the scratch tape request as if this exit had 
not been called. 

04 (X’04’) Replace the scratch tape request with a specific volume 
serial number. Do this by loading the address of a 
6-byte volume serial number into register 0. 


Note: A value other than 0 or 4 in register 15 is treated as a 0. 


If OPEN or EOV finds that the volume pointed to by register 0 is being used 
either by this or by another job (an active ENQ on this volume), it takes this exit 
again and continues to do so until you either specify another volume serial 
number or request a scratch volume. If the volume you specify is available but is 
rejected by OPEN or EOV for some reason (I/O errors, expiration date, 
password check, and so forth), this exit is not taken again. 


When this exit gets control, register 1 points to the parameter list described by the 
IECOENTE macro. Figure 26 shows this parameter list. 


CL4 PLIST ID ('OENT' ) 

X FLAG BYTES 

X'80' O=OPEN, 1=E0OV 

x'o1' O=1ST ENTRY ,1=SUBSEQUENT ENTRY 
X OPEN OPTION (OUTPUT/INPUT/...) 
X'OF' TO MASK OFF UNNECESSARY BITS 
XL2 RESERVED 

A ADDRESS OF USER DCB 

A ADDRESS OF VOLSER 

A ADDRESS OF 0/C/E COPY OF JFCB 
*-&1 PLIST LENGTH 

6F REGISTER SAVE AREA 


*-OENTE MACRO LENGTH 


Figure 26. IECOENTE Macro Parameter List 


OENTOEOV | 
set to 0 if OPEN called this exit; set to 1 1f EOV called this exit. 


OENTNTRY 
set to | if this is not the first time this exit was called because the requested 
tape volume is being used by this or any other job. 


OENTOPTN | 
contains the OPEN options from the DCB parameter list (OUTPUT, 
INPUT, OUTIN, INOUT, and so forth). For EOV processing, the 
options byte in the DCB parameter list indicates how EOV 1s processing 
this volume. For example, if you open a tape volume for INOUT and 
EQOV is called during an input operation on this tape volume, the DCB 
parameter list and OENTOPTN are set to indicate INPUT. 
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OENTVSRA | | a q 
| points to the last volume serial number you requested in this exit but was S 
in use either by this or another job. OENTVSRA 1s set to 0 the first tume 
this exit 1s called. 


OENTJFCB = | 
points to the OPEN or EOV copy of the JFCB. The high order bit is 
always on, indicating that this is the end of the parameter list. 


OENTREGS 
starts the register save area used by OPEN or EOV. Do not use this save 
area in this user exit. 


Convention for Saving and Restoring General Registers 


When this user exit is entered, the general registers contain: 


Register Contents 


0 Variable 

l Address of the parameter list for this exit 

2-13 Contents of the registers before the OPEN or EOV was 
issued 

14 Return address (you must preserve the contents of this 
register in this user exit) 

15 Entry point address to this user exit 


You do not have to preserve the contents of any register other than register 14. 
The operating system restores the contents of registers 2 through 13 before it 
returns to OPEN or EQOV and before it returns control to the onginal calling 
program. os 


Do not use the save area pointed to by register 13; the operating system uses it. 
If you call another routine, or issue a supervisor or data management macro in | 
this user exit, you must provide the address of a new save area in register 13. 


Open/EOV Volume Security and Verification Exit 


This user exit lets you verify that the volume that 1s currently mounted 1s the one 
you want. You can also use it to bypass the OPEN or EOV expiration date, 
password, and data set name security checks. A X’18’ in the DCB exit list 
(EXLST) activates this exit. (See “Exit List (EXLST)” on page 80 for more 
information about EXLST.) This exit, which supports IBM standard label tapes, 
was designed to be used with the OPEN/EOV nonspecific tape volume mount 
user exit. (See “Open/EOV Nonspecific Tape Volume Mount Exit” on page 88 
for more information about that user exit.) However, this exit can be used by 
itself. 





Note: This exit is available only for APF-authorized programs. 
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( This user exit gets control in the key and state of the program that issued the 
- OPEN or EOV request, and no locks are held. After you are in control, you 
must provide a return code in register 15. 


Return Code Meaning 


00 (X’00’) Use this tape volume. Return to OPEN or EOV as if 
this exit had not been called. 


04 (X'04’) Reject this volume and: 
e Output 


— If the data set is the first data set on the volume, 
request a scratch tape. This causes OPEN or 
EOV to issue demount message IEC5S02E for 
the rejected tape volume, and mount message 
IECSO1A for a scratch tape volume. If the 
nonspecific tape volume mount exit is active, it 
is called. 


— Ifthe data set is other than the first one on the 
volume, process this return code as if it were 
return code 08. 


e Input 


— Treat this return code as if it were return code 
08. 


08 (X’08’) Abnormally terminate OPEN or EOV unconditionally; 
no scratch tape request is issued. 


Open abnormally terminates with a 913-34 abend code, 
and EOV terminates with a 937-29 abend code. 


12 (X’0C’) Use this volume without checking the data set’s 
expiration date, but check its password and name. If the 
expiration date of the current data set is in effect, the 
new data set can still write over it. 


16 (X‘10’) Use this volume. A conflict with the password, label 
expiration date, or data set name does not prevent the 
new data set from writing over the current data set if it 
is the first one on the volume. To write over other than 
the first data set, the new data set must have the same 
level of security protection as the current data set. 


When this exit gets control, register 1 points to the parameter list described by the 
IECOEVSE macro. The parameter list appears as: 
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+ OEVSID DS  CL4 ID FIELD = OEVS 

+ OEVSFLG DS X FLAGS BYTE 

+ OEVSEOV EQU- x'80' O=OPEN, 1=EOV 

+ OEVSFILE EQU- x'O1' O=1ST FILE, 1=SUBSEQ FILE 

* BITS 1 THROUGH 6 RESERVED 

+ OEVSOPTN DS X OPEN OPTION (OUTPUT/INPUT/...) 

+ OEVSMASK EQU- X'OF' MASK 

+ OEVSRSVD DS XL2 RESERVED 

+ OEVSDCBA DS A ADDRESS OF USER DCB 

+ OEVSVSRA DS A ADDRESS OF 6-BYTE VOLSER 

+ OEVSHDR1 DS A ADDRESS OF HDR1/EOF1 

+ OEVSJFCB DS A ADDRESS OF 0/C/E COPY OF JFCB 

+ OEVSLENG EQU *-&L PLIST LENGTH 

+ OEVSREGS DS 6F REGISTER SAVE AREA 

+ OEVSAREA EQU  *-OEVSE MACRO LENGTH 

Figure 27. IECOEVSE Macro Parameter List 

OEVSFLG 

a flag field containing two flags. 
OEVSEOV is set to 0 if OPEN called this exit; set to 1 if EOV called this 
exit. 
OEVSFILE is set to 0 if the first data set on the volume is to be written; be | y 


set to 1 if this 1s not the first data set on the volume to be written. This bit 
is always 0 for INPUT processing. 


OEVSOPTN 
a 1-byte field containing the OPEN options from the DCB parameter list 
(OUTPUT, INPUT, INOUT, and so forth). For EOV processing, this 
byte indicates how EOV is processing this volume. For example, if you 
opened a tape volume for OUTIN and EOV is called during an output 
operation on the tape volume, the DCB parameter list and OEVSOPTN 
are set to indicate OUTPUT. 


OEVSVSRA 
a pointer to the current volume serial number that OPEN or EOV 1s 
processing. 


OEVSHDRI 
a pointer to a HDR1 label, if one exists; or an EOF1 label, if you are 
creating other than the first data set on this volume. 


OEVSJFCB 
a pointer to the OPEN, CLOSE, or EOV copy of the JFCB. The 
high-order bit is always on, indicating that this is the end of the parameter 
list. 


OEVSREGS 
a register save area used by OPEN or EOV. Do not use this save area in 
this user exit. 
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Convention for Saving and Restoring General Registers 


When this user exit is entered, the general registers contain: 


Register Contents 


0 Variable 

l Address of the parameter list for this exit. 

2-13 Contents of the registers before the OPEN or EOV was 
issued 

14 Return address (you must preserve the contents of this 
register in this user exit) 

15 Entry point address to this user exit 


You do not have to preserve the contents of any register other than register 14. 
The operating system restores the contents of registers 2 through 13 before it 
returns to OPEN or EOV and before it returns control to the original calling 
program. 


Do not use the save area pointed to by register 13; the operating system uses it. 
If you call another routine or issue a supervisor or data management macro in 
this user exit, you must provide the address of a new save area in register 13. 


QSAM Parallel Input Exit 


JFCBE Exit 


A request for parallel input processing is indicated by including the address of a 
parallel data access block (PDAB) in the DCB exit list. The address must be on 
a fullword boundary with the first byte of the entry containing X‘’12’ or, if it 1s 
the last entry, X’92’. For more information on parallel input processing, see 
“Parallel Input Processing (QSAM Only)” on page 66. 


JCL-specified setup requirements for the IBM 3800 Printing Subsystem cause a 
JFCB extension (JFCBE) to be created to reflect those specifications. A JFCBE 
exists if BURST, MODIFY, CHARS, FLASH, or any copy group is coded on 
the DD statement. The JFCBE exit can be used to examine or modify those 
specifications in the JFCBE. The address of the routine should be placed in an 
exit list. (The device allocated does not have to be a 3800.) This exit is taken 
during OPEN processing and is mutually exclusive with the data control block 
exit. If you need both the JFCBE and data control block exits, you must use the 
JFCBE exit to pass control to your routines. 


With a 3800, when you issue the SETPRT macro to a SYSOUT data set, the 
JFCBE is further updated from the information in the SETPRT parameter list. 


When control is passed to your exit routine, the contents of register | will be the 
address of the DCB being processed. 


The area pointed to by register 0 will also contain the 4-byte FCB identification 
that is obtained from the JFCB. The FCB identification is placed in the 4 bytes 
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A aN 
following the 176-byte JFCBE. If the FCB operand was not coded on the DD a | 


statement, this FCB field will be binary zeros. Se 


If your copy of the JFCBE is modified during an exit routine, you should 
indicate this fact by turning on bit JECBEOPN (X’80’ in JECBFLAG) in the 
JFCBE copy. On return to OPEN, this bit indicates whether the system copy is 
to be updated. The 4-byte FCB identification in your area will be used to update 
the JFCB regardless of the bit setting. Checkpoint/restart also interrogates this 
bit to determine which version of the JFCBE will be used at restart tume. If this 
bit is not on, the JFCBE generated by the restart JCL will be used. 


End-of-Volume Exit 


Block Count Exit 


You can specify in an exit list the address of a routine that is entered when 
end-of-volume is reached in processing of a physical sequential data set. 


When you concatenate data sets with unlike attributes, no EOV exits are taken. 


When the end-of-volume routine is entered, register 0 contains 0 unless user 
totaling was specified. If you specified user totaling in the DCB macro (by 
coding OPTCD=T) or in the DD state:::ent for an output data set, register 0 
contains the address of the user totaling image area. The routine is entered after 
a new volume has been mounted and all necessary label processing has been 
completed. If the volume is a reel of magnetic tape, the tape is positioned after 


the tapemark that precedes the beginning of the data. ved 


You can use the end-of-volume (EOV) exit routine to take a checkpoint by 
issuing the CHKPT macro, which is discussed in Checkpoint/Restart. Ifa 
checkpointed job step terminates abnormally, it can be restarted from the EOV 
checkpoint. When the job step is restarted, the volume is mounted and 
positioned as upon entry to the routine. Restart becomes impossible if changes 
are made to the link pack area (LPA) library between the time the checkpoint is 
taken and the time the job step is restarted. When the step is restarted, pointers 
to end-of-volume modules must be the same as when the checkpoint was taken. 


The end-of-volume exit routine returns control in the same manner as the data 
control block exit routine. The contents of register 14 must be preserved and 
restored if any macros are used in the routine. Control is returned to the 
operating system by a RETURN macro; no return code 1s required. 


You can specify in an exit list the address of a routine that will allow you to 
abnormally terminate the task or continue processing when the end-of-volume 
routine finds an unequal block count condition. When you are using standard 
labeled input tapes, the block count in the trailer label 1s compared by the 
end-of-volume routine with the block count in the DCB. The count in the trailer 
label reflects the number of blocks written when the data set was created. The 
number of blocks read when the tape is used as input is contained in the 
DCBBLKCT field of the DCB. 


94 MVS/XA Data Administration Guide 




















The routine is entered during end-of-volume processing. The trailer label block 
count is passed in register 0. You may gain access to the count field in the DCB 
by using the address passed in register | plus the proper displacement, as 
explained in Debugging Handbook. If the block count in the DCB differs from 
that in the trailer label when no exit routine is provided, the task is abnormally 
terminated. The routine must terminate with a RETURN macro and a return 
code that indicates what action is to be taken by the operating system, as shown 
in Figure 28. As with other exit routines, the contents of register 14 must be 
saved and restored if any macros are used. 
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Return Code System Action 
0 (X’00’) The task is to be abnormally terminated. 
4 (X’04’) Normal processing is to be resumed. 


Figure 28. System Response to Block Count Exit Return Code 


Defer Nonstandard Input Trailer Label Exit 


FCB Image Exit 


In an exit list, you can specify a code that indicates that you want to defer 
nonstandard input trailer label processing from end-of-data until the data set is 
closed. The address portion of the entry is not used by the operating system. 


An end-of-volume condition exists in several situations. Two examples are: (1) 
when the system reads a filemark or a tapemark at the end of a volume of a 
multivolume data set but that volume 1s not the last, and (2) when the system 
reads a filemark or a tapemark at the end of a data set. The first situation is 
referred to here as an end-of-volume condition, and the second as an end-of-data 
condition, although it, too, can occur at the end of a volume. 


For an end-of-volume (EOY) condition, the EOV routine passes control to your 
nonstandard input trailer label routine, whether or not this exit code is specified. 
For an end-of-data condition when this exit code is specified, the EOV routine 
does not pass control to your nonstandard input trailer label routine. Instead, the 
close routine passes control to your end-of-data routine. 


You can specify in an exit list the address of a forms control buffer (FCB) image. 
This FCB image can be loaded into the forms control buffer of the printer 
control unit. The FCB controls the movement of forms in printers that do not 
use a carriage control tape. 


Multiple exit list entries in the exit list can define FCBs. The OPEN and 
SETPRT routines search the exit list for requested FCBs before searching 
SYSLIMAGELIB. 
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The first 4 bytes of the FCB image contain the image identifier. To load the 
FCB, this image identifier is specified in the FCB parameter of the DD 
statement, by the SETPRT macro, or by the ae Operator in response to 
message TEC127D or TEC129D. 


For an IBM 3203 or 3211 Printer, the 1 image identifier ; is followed by the FCB 
image described in System-Data Administration. For a 3800 FCB image, see 
IBM 3800 Printing Subsystem Programmer's Guide. 


You can use an exit list to define an FCB image only when writing to an online 
printer. Figure 29 illustrates one way the exit list can be used to define an FCB 





image. 

DCB .. yEXLST=EXLIST 

EXLIST DS OF 
DC X'10' Flag code for FCB image 
DC AL3(FCBIMG ) Address of FCB image 

i DC x’ 80000000 End of EXLST and a null entry 

FCBIMG DC CLA! IMG1' FCB identifier 
DC x'00!' FCB is not a default 
DC AL1(67 ) Length of FCB 
DC x'90' Offset print line 

* 16 line character positions to the right 
DC X'00' Spacing is 6 lines per inch 
DC 5x'00' Lines 2-6, no channel codes aa 
DC Xx'o1' Line 7, channel 1 Lo 
DC 6x'00' Lines 8-13, no channel codes ay 
DC X'02' Line (or Lines) 14, channel 2 
DC 5X'00' Line (or Lines) 15-19, no channel codes 
DC Xx'03' Line (or Lines) 20, channel 3 
DC 9X'00' Line (or Lines) 21-29, no channel codes 
DC X'04' Line (or Lines) 30, channel 4 
DC 19xX'00' Line (or Lines) 31-49, no channel codes 
DC X'05' Line (or Lines) 50, channel 5 
DC X'06' Line (or Lines) 51, channel 6 
DC X'07' Line (or Lines) 52, channel 7. 
DC X'08' Line (or Lines) 53, channel 8 
DC Xx'09' Line (or Lines) 54, channel 9 
DC X'OA' Line (or Lines) 55, channel 10 
DC X' OB! Line (or Lines) 56, channel 11 
DC X'0C' Line (or Lines) 57, channel 12 
DC 8X'00' Line (or Lines) 58- 65, no channel codes 
DC Xx'10' End of FCB image 
END | 

a DD UNIT=3211,FCB=( IMG1, VERIFY) 


Figure 29. Defining an FCB Image for a 3211 
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DCB Abend Exit 





The DCB abend exit is provided to give you some options regarding the action 
you want the system to take when a condition arises that may result in abnormal 
termination of your task. This exit can be taken any time an abend condition 
arises during the process of opening, closing, or handling an end-of-volume 
condition for a DCB associated with your task. 


When an abend condition arises, a write-to-programmer message about the abend 
is issued and your DCB abend exit 1s given control, provided there is an active 
DCB abend exit routine address in the DCB being processed. If STOW called 
the end-of-volume routines to get secondary space to write an end-of-file mark 
for a partitioned data set, or if the DCB being processed is for an indexed | 
sequential data set, the DCB abend exit routine will not be given control if an 
abend condition occurs. The contents of the registers when your exit routine 1s 
entered are the same as for other DCB exit list routines, except that the 3 
low-order bytes of register 1 contain the address of the parameter list described in 
Figure 30 on page 98. Your abend exit routine can choose one of four options: 


e To immediately terminate your task 


e To delay the abend until all the DCBs in the same OPEN or CLOSE macro 
are opened or closed 


¢ To ignore the abend condition and continue processing without making 
reference to the DCB on which the abend condition was encountered, or 


e To try to recover from the error 


Not all of these options are available for each abend condition. Your DCB 
abend exit routine must determine which option 1s available by examining the 
contents of the option mask byte (byte 3) of the parameter list. The address of 
the parameter list 1s passed in register 1. Figure 30 on page 98 shows the 
contents of the parameter list and the possible settings of the option mask when 
your routine receives control. (All information in the parameter list is in binary.) 
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Bit Meaning 


Reserved for System Use 





1-3 Reserved for Future Use 
pa OK to Recover 
OK to Ignore 
Za OK to Delay 


Reserved for Future Use 


Fullword Boundary 


System Compietion Code! Option Mask | pe vis 
eaeneen ee , : | —— 


DCB Address 


Cisplacement 








ion ee patrecreerr® mente 


Onen/Close/End-of-Volume Work Area Address 


| Recovery Work Area Address _ 


Vin the first 12 bits. 





Figure 30. Parameter List Passed to DCB Abend Exit Routine 
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When your DCB abend exit routine returns control to the system control 
program (this can be done using the RETURN macro), the option mask byte 
should contain the setting that specifies the action you want to take. These 
actions and the corresponding settings of the option mask byte are: 





Decimal 

Value Action 

0 Abnormally terminate the task immediately. 

4 Ignore the abend condition. 

8 Delay the abend until the other DCBs being processed concurrently cr 
are opened or closed. a 

b2: _ Make an attempt to recover. 
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You must inspect bits 4, 5, and 6 of the option mask byte (byte 3 of the 
parameter list) to determine which options are available. Ifa bit is set to 1, the 
corresponding option is available. Indicate your choice by inserting the 
appropriate value in byte 3 of the parameter list, overlaying the bits you 
inspected. If you use a value that specifies an option that is not available, the 
abend is issued immediately. 


If the contents of bits 4, 5, and 6 of the option mask are 0, you must not change 
the option mask. This unchanged option mask will result in a request for an 
immediate abend. 


If bit 5 of the option mask is set to 1, you can ignore the abend by placing a 
value of 4 in byte 3 of the parameter list. Processing on the current DCB stops. 
If you subsequently attempt to use this DCB, the results are unpredictable. If 
you ignore an error in end-of-volume, control is returned to your program at the 
point that caused the end-of-volume condition (unless the end-of-volume routines 
were called by the close routines). If the end-of-volume routines were called by 
the close routines, an ABEND macro will be issued even though the ignore 
option was selected. 


If bit 6 of the option mask is set to 1, you can delay the abend by placing a value 
of 8 in byte 3 of the parameter list. All other DCBs waiting for OPEN or 
CLOSE processing will be processed before the abend is issued. For 
end-of-volume, however, you can’t delay the abend because the end-of-volume 
routine never has more than one DCB to process. 


If bit 4 of the option mask is set to 1, you can attempt to recover. Place a value 
of 12 in byte 3 of the parameter list and provide information for the recovery 
attempt. Figure 31 lists the abend conditions for which recovery can be: 
attempted. For abend conditions that can be ignored or delayed, see System 
Messages. 


System 
Completion 
Code Description of Error 


An I/O error occurred during 
execution of a read block ID 


command issued to establish tape 
position. 


DCB block count did not agree 
with the calculated block count. 





Figure 31 (Part 1 of 3). Conditions for Which Recovery Can Be Attempted 
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System 
Completion | Return wa? 
Code | Code Description of Error 


137 : DCB block count did not agree 
with the calculated block count. 


An I/O error occurred while 
positioning a magnetic tape data set 
to the first data record or during 
execution of a read block ID 
command issued to establish tape 
position. 


An I/O error occurred during 
execution of a read block ID 
command issued to establish tape 





position. 
213 X’04’ DSCB was not found on volume 
specified. 


214 : An I/O error occurred during 
execution of a read block ID 
command issued to establish tape 


position. 


DCB block count did not agree 
with the calculated block count. 


X04’ Block count in DCB does not agree 
with block count in trailer label. 
X18’ Data set was opened for input and 
no volume serial number was 
specified. 


I/O error occurred during reading 
of tape label. 










Invalid tape label was read. 







I/O error occurred during writing of 
tape label. 







I/O error occurred during writing of 
tape label. 





X’04’ A data set on magnetic tape was 
opened for INOUT, but the 
volume contained a data set whose 
expiration date had not been 
reached and the operator denied 


permission. 


X10’ I/O error occurred during reading 
of trailer label 1 to update block 
count in DCB. 


Figure 31 (Part 2 of 3). Conditions for Which Recovery Can Be Attempted 
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System 
Completion 
Code Description of Error 


Data set name on header label does 
not match data set name on DD 
Statement. 





Figure 31 (Part 3 of 3). Conditions for Which Recovery Can Be Attempted 


Recovery Requirements 


For the recovery attempt, you should supply a recovery work area (see Figure 32 
on page 102) with a new volume serial number for each volume associated with 
an error. If no new volumes are supplied, recovery will be attempted with the 
existing volumes, but the likelihood of successful recovery is greatly reduced. 


If you request recovery for system completion code 213, return code 04, you 
must indicate in your job control language (JCL) that the volumes cannot be 
shared by specifying unit affinity, deferred mounting, or more volumes than units 
for the data set. 


If you request recovery for system completion code 237, return code 04, you 
don’t need to supply new volumes or a work area. The condition that caused the 
abend 1s the disagreement between the block count in the DCB and that in the 
trailer label. To permit recovery, this disagreement is ignored. 


If you request recovery for system completion code 717, return code 10, you 
don’t need to supply new volumes or a work area. The abend is caused by an 
I/O error during updating of the DCB block count. To permit recovery, the 
block count is not updated. Consequently, an abnormal termination with system 
completion code 237, return code 04, may result when you try to read from the 
tape after recovery. You may attempt recovery from the abend with system 
completion code 237, return code 04, as explained in the preceding paragraph. 


Svstem completion codes and their associated return codes are described in 
System Codes. 
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Halfword Boundary 


Displacement 


Figure 32. 


0 


Length of This Work Area Option Byte 





Bit 


Free This Work Area 


Volume Serial Numbers Are 
Provided 


Reserved for Future Use 


N ; 
“J 


Subpool Number 


4 Number of 
New Volumes New Volume Serial Numbers (6 bytes each) 


Recovery Work Area 


The work area that you supply for the recovery attempt must begin on a 
halfword boundary and can contain the information described in Figure 32. 
Place a pointer to the work area in the last 3 bytes of the parameter list pointed 
to by register 1 and described in Figure 30 on page 98. 


If you acquire the storage for the work area by using the GETMAIN macro, you 
can request that it be freed by a FREEMAIN macro after all information has 
been extracted from it. Set the high-order bit of the option byte in the work area 
to 1 and place the number of the subpool from which the work area was 
requested in byte 3 of the recovery work area. 


Only one recovery attempt per data set is allowed during OPEN, CLOSE, or 
end-of-volume processing. If a recovery attempt is unsuccessful, you may not 
request another recovery. The second time through the exit routine you may 
request only one of the other options (if allowed): Issue the abend immediately, 
ignore the abend, or delay the abend. If at any time you select an option that is 
not allowed, the abend is issued immediately. 


Note that, if recovery is successful, you still receive an abend message on your 
listing. This message refers to the abend that would have been issued if the 
recovery had not been successful. 
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Abend Installation Exit 


The abend installation exit gives you an additional option for handling error 
situations that result in an abend. This exit is taken any time an abend condition 
occurs during the process of opening, closing, or handling an end-of-volume 
condition for a DCB. An IBM-supplied installation exit will give you the option 
to retry tape positioning when you receive a 613 system completion code, return 
code 08 or OC. (For additional information about the abend installation exit, see 
Spstem— Data Administration and Open/Close/EOV Logic.) 
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Chapter 8. Spooling and Scheduling Data Sets 


The job entry subsystem (JES) is a system function that spools and schedules 
input and output data streams. 


Spooling includes two basic functions: 


e Input streams are read from the input device and stored on an intermediate 
storage device in a format convenient for later processing by the system and 
by the user’s program. 


¢ Output streams are similarly stored on an intermediate device until a 
convenient time for printing or punching. 


Scheduling provides the highest degree of system availability through the orderly 
use of system resources that are the objects of contention. 


( | With spooling, unit record devices are used at full rated speed if enough buffers 

. are available, and they are used only for the time needed to read, print, or punch 
the data. Without spooling, the device is occupied for the entire time that a job 
is doing other processing. Also, because data is stored instead of being 
transmitted directly, output can be queued in any order and scheduled by class 
and by priority within each class. 


You enter data into the system input stream by preceding it with a DD * ora 
DD DATA JCL statement. This 1s a SYSIN data set. 


Your output data can be printed or punched from a SYSOUT data set that 1s 
referred to as the output stream. You code the SYSOUT keyword parameter in 
your DD statement and designate the appropriate output class. For example, 
SYSOUT=A requests output class A. The class-device relationship 1s 
established for each installation, and a list of devices assigned to each output class 
will enable you to select the appropriate one. For further information on SYSIN 
and SYSOUT parameters, see JCL 


SYSIN and SYSOUT must be either BSAM or QSAM data sets and you open 
and close them in the same manner as any other data set processed on a unit 
record device (except when multiple DCBs are used to write to the same output 
class, the records are not interspersed.) The job entry subsystem (JES) allows 
multiple opens to SYSOUT data sets. However, serialization of the data set is 
the responsibility of the application or user. The DCB exit routine will be 
entered in the usual manner if you specify it in an exit list. 





When you use QSAM with fixed-length blocked records or BSAM, the DCB 
block size parameter does not have to be a multiple of logical record length 
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(LRECL) if the block size is specified through the SYSOUT DD statement. 
Under these conditions, if block size is greater than LRECL but not a multiple of 
LRECL, block size is reduced to the nearest lower multiple of LRECL when the 
data set is opened. This feature allows a cataloged procedure to specify blocking 
for SYSOUT data sets, even though your LRECL is not known to the system 
until execution. 


Therefore, the SYSOUT DD statement of the go step of a compile-load-go 
procedure can specify block size without block size being a multiple of LRECL. 


Because a SYSOUT data set is written on a direct access device, you should omit 
the DEVD operand in the DCB macro, or you should code DEVD= DA. 
Because SYSIN and SYSOUT data sets are spooled on intermediate devices, you 
should also avoid using device-dependent macros (such as FEOV, CNTRL, 
PRTOV, BSP, or SETPRT) in processing these data sets. (See “Device 
Independence” on page 58.) With a 3800, you can use SETPRT when 
processing spooled data sets. For further information, refer to [BM 3800 Printing 
Subsystem Programmer's Guide. 


The job entry subsystem controls all blocking and deblocking of your data to 
optimize system operation and ignores the number of channel programs (NCP) 
you specify. The block size (BLKSIZE) and number of buffers (BUFNO) 
specified in your program have no correlation with what is actually used by the 
job entry subsystem. Therefore, you can select the blocking factor that best fits 
your application program with no effect on the spooling efficiency of the system. 
For QSAM applications, move mode is as efficient as locate mode. © 


All record formats are allowed, except that spanned records (RECFM = VS or 
VBS) cannot be specified for SYSIN. A record format of FIXED is supplied if it 
is not specified for SYSIN. 


The minimum record length for SYSIN is 80 bytes. For undefined records, the 
entire 80-byte image is treated as a record. Therefore, a read of less than 80 bytes 
results in the transfer of the entire 80-byte image to the record area specified in 
the READ macro. For fixed and variable nel records, an abend results if the 
LRECL is less than 80 bytes. | 


The logical record length value (JFCLRECL field in the JFCB) 1s filled in with — 
the logical record length value of the input data set. This value is increased by 4 
if the record format is variable (RECFM= V or VB). The logical record length 
may be a size other than the size of the input device, if the SYSIN input stream 
is supplied by an internal reader. The job entry subsystem will supply a value in 
the JFCLRECL field of the JFCB if that field 1s found to be zero. 


The block size value (JFCBLKSI field in the JFCB) is filled in with the block 
size value of the input data set. This value is increased by 4 greater than the 
value calculated for the logical record value (that is, input data set logical record 
length + 4) if the record format is variable (RECFM=V or VB). The job entry 
subsystem will supply ¢ a value in the J FCBLKSI field of the JFCB if that field 3 1S 
found to be 0. 
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Your program is responsible for printing format, pagination, header control, and 
stacker select. You can supply control characters for SYSOUT data sets in the 
normal manner by specifying ANSI or machine characters in the DCB. Standard 
controls are provided by default if they are not specified. The length of output 
records must not exceed the allowable maximum length for the ultimate device. 
Cards can be punched in EBCDIC mode only. 


Your SYNAD routine will be entered if an error occurs during data transmission 


to or from an intermediate storage device. Again, because the specific device is 
indeterminate, your SYNAD routine code should be device independent. 
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Chapter 9. Processing a Sequential Data Set 


Data sets residing on any volume other than direct access volumes must be 
processed sequentially. In addition, a data set residing on a direct access volume, 
regardless of organization, can be processed sequentially. This includes data sets 
created using ISAM or a similar access method. Because the entire data set 
(prime, index, and overflow areas) will be processed, care should be taken to 
determine. the type of records being processed. 


Either the queued or the basic access technique may be used to store and retrieve 
the records of a sequential data set. For a non-DASD sequential data set, a 
technique called chained scheduling can be used to accelerate the input/output 
operations. 


Creating a Sequential Data Set 


As discussed earlier, a processing program should be developed using, as much as 
possible, factors that are constant, with variable factors specified at execution. 
For that reason, the following examples are generalized as much as possible. 
They are neither exhaustive nor intended as complete examples. Rather, they are 
presented as introductory sequences. 


In creating a sequential data set on a magnetic tape or direct access device, you 
must do the following: 


¢ Code DSORG= PS or PSU in the DCB macro. 
¢ Code a DD statement to describe the data set (see /CL). 


e Process the data set with an OPEN macro (data set 1s opened for output or 
OUTIN), a series of PUT or WRITE and CHECK macros, and then a 
CLOSE macro. 


Tape-to-Print, Move Mode—Simple Buffering: The example in Figure 33 on 
page 110 shows that the GET-move and PUT-move require two movements of 
the data records. If the record length (LRECL) does not change dunng 
processing, only one move is necessary; you can process the record in the input 
buffer segment. A GET-locate can be used to provide a pointer to the current 
segment. 
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NEXTREC 


TAPERROR 


ake 
“7 


ENDJOB 


COUNT 
WORKAREA 
NUMBER 
SAVE14 
INDATA 


OUTDATA 


OPEN 
GET 
AP 
UNPK 
PUT 


B 
SYNADAF 
LA 


ST 

PUT 
SYNADRLS 
L 


RETURN 
CLOSE 
DS. 

DS 

DC 


DS 
DCB 








(INDATA, , OUTDATA, (OUTPUT) ) 


INDATA, WORKAREA Move mode 

NUMBER, =P' 1' 

COUNT , NUMBER Record count adds 6 

OUTDATA , COUNT bytes to each record 

NEXTREC 

ACSMETH=QSAM Control program returns 

0,68(0,1) message address in regis- 

| ter l. 

14, SAVE14 SYNAD routine prints part 

OUTDATA, (0) of the message (beginning 
with the unit number) as 

14,SAVE14 a 56-byte fixed-length 
record. It then returns 

(INDATA, , OUTDATA) to the control program. 

CL6 

CL50 

PL4'0' 

F 

DDNAME=INPUTDD , DSORG=PS , MACRF=(GM) , EROPT=ACC, C 


SYNAD=TAPERROR , EODAD=ENDJOB 


DCB 


DDNAME=OUTPUTDD , DSORG=PS , MACRF=( PM) , EROPT=ACC 


Figure 33. Creating a Sequential Data Set—Move Mode, Simple Buffering 


Retrieving a Sequential Data Set 


In retrieving a sequential data set on a magnetic tape or a direct access device, 
you must do the following: 


e Code DSORG= PS or PSU in the DCB macro. 


@ Tell the system where your data set is located (by coding a DD statement; see 
JCL). 


e Process the data set with an OPEN macro (data set is opened for input, 
INOUT, RDBACK, or UPDAT), a series of GET or READ macros, and 
then a CLOSE macro. 


Tape-to-Print, Locate Mode—Simple Buffering: The example in Figure 34 on 
page 111 is similar to that in Figure 33. However, because there is no change in 
the record length, the records can be processed in the input buffer. Only one 
move of each data record is required. 
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NEXTREC 


TAPERROR 


MOVERCD 
PRINTIT 


ENDJOB 


NUMBER 
INDATA 


OUTDATA 
ERRORDCB 


SAVE2 


Figure 34. 


OPEN 
GET 
LR 
AP 
UNPK 
PUT 
MVC 


B 
SYNADAF 
ST 

L 

MVC 

MVI 

MVC 

ST 

CH 

BE 

BL 

CLI 

BE 

MVC 

LA 

LR 

PUT 
SYNADRLS 
LR 

Li. 
RETURN 
CLOSE 
DC 
DCB 
DCB 
DCB 


DS 








ey AAPA SOLAS lh POLIS AIA ABATE D1 DREN SLSR TAD RAP (SSRI OSES AANA SAEED 


(INDATA, ,OUTDATA, (OUTPUT) , ERRORDCB, (OUTPUT) ) 


INDATA 

21 

NUMBER, =p'y' 
0(6,2),NUMBER 
OUTDATA 
0(50,1),0(2) 
NEXTREC _ 
ACSMETH=QSAM 
2, SAVE2 
2,8(0,1) . 
8(70, 1) ,50(1) 
78(1),C 
79(49,1),78(1) 
2 ,128(1) 
0,=H'4 

MOVERCD 
PRINTIT 
128(1),c' ' 
PRINTIT 
78(50,1),0(2) 
0,4(1) 

2,14 
ERRORDCB, (0) 


14,2 
2, SAVE2 


Locate mode 
Save pointer 


Process in input area 
Locate mode 
Move record to output buffer 


Message address in register l 
Save register 2 contents 

Load pointer to input buffer 
Shift nonblank message fields 
Blank end of message | 


Save address for debugging 
Test SYNADAF return code 
Branch if data read 

Branch if data not read 

See if data read anyway 
Branch if definitely no data 
Add input record to message 
Load address of message 

Save return address 

Print message (move mode) 
Release message and save area 
Restore return address 
Restore register 2 contents 
Return to control program 


CINDATA, , OUTDATA, , ERRORDCB ) 


PL4'0' 


DDNAME=INPUTDD , DSORG=PS , MACRF=(GL) , EROPT=ACC, 


SYNAD=TAPERROR , EODAD=ENDJOB 


DDNAME=OUTPUTDD , DSORG=PS , MACRF=(PL) 
DDNAME=SYSOUTDD , DSORG=PS , MACRF=(PM) , RECFM=V, 


BLKSIZE=128, LRECL=124 
ee 


Creating a Sequential Data Set—Locate Mode, Simple Buffering 
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Modifying a Sequential Data Set - - 


You can modify a sequential data set in two ways: 
® Changing the data in existing records (update in place) 


e Adding new records to the end of a data set (extending the data set) 


Updating a Sequential Data Set in Place 


When you update in place, you read records, process them, and write them back 
to their onginal positions without destroying the remaining records on the track. 
The following rules apply: 


e You must specify the update option (UPDAT) in the OPEN macro— 
instruction. To perform the update, you can use only the READ, WRITE, 
CHECK, NOTE, POINT, GET, and PUTX macros. 


e You cannot delete any record or change its length; you cannot add new 
records. | 


® The data set must be on a direct access device. 


A record must be retrieved by a READ or GET macro before it can be updated 
by a WRITE or PUTX macro. A WRITE or PUTX macro does not need to be i 
issued after each READ or GET macro. The READ and WRITE macros must “ 
be execute forms that refer to the same DECB; the DECB must be provided by 

the list forms of the READ or WRITE macros. (The execute and list forms of 

the READ and WRITE macros are described 1 in Data Administration: Macro 

Instruction Reference.) 


Updating with Overlapped Operations 


To overlap input/output and processor activity, you can start several read or 
write operations before checking the first for completion. You cannot overlap 
read with write operations, however, as operations of one type must be checked 
for completion before operations of the other type are started or resumed. Note 
that each pending read or write operation requires a separate channel program — 
and a separate DECB. If a single DECB were used for successive read 
operations, only the last record read could be updated. 


In Figure 52 on page 145, overlap is achieved by having a read or write request 
outstanding while each record is being processed. Note the use of the execute 
and list forms of the READ and WRITE macros, identified by the operands 
MF=E and MF=L. 
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Extending a Sequential Data Set 





If you want to add records at the end of your data set, you must open the data 
set for output with DISP= MOD specified in the DD statement or specify the 
EXTEND option of the OPEN macro. You can then issue PUT or WRITE 

macros to the data set. 


Concatenating Sequential Data Sets 


Concatenation 1s a method by which a collection of sequential data sets can be 
treated by the application program as one data set. For example, two or more 
sequential data sets can be automatically retrieved by the system and processed 
successively as a single data set. It is important to consider the characteristics of 
the individual data sets being concatenated. Data sets with like characteristics are 
those that may be processed correctly using the same data control block (DCB), 
input/output block (IOB), and channel program. Any variation is as record 
format, device, or option) makes them unlike. 


Differing block sizes make data sets unlike unless the first block size in the 
concatenation is greater than any block size following. However, the system will 
automatically adjust buffers and channel programs for eligible data sets, if 
necessary. The primary purpose of this service is to permit otherwise 
homogeneous data sets to be concatenated in any order. Eligibility rules are: 


Data set resides on DASD 

RECFM cannot be U (RECFM can be F or ¥) 
Records are blocked 

LRECL is same for all data sets being eencaeaied 
Access method is QSAM 

OPEN got the buffer pool 

Block size was not coded in the DCB macro 


| Note: Block size can be coded in DD statements, via TSO ALLOCATE 
| commands, or 1n the data set label. 


When sequential data sets are concatenated, the system is open to only one of the 
data sets at a time. You must inform the system by modifying the DCBOFLGS 
field of the DCB if unlike sequential data sets are concatenated (this is not 
required for spool data sets, because EOV automatically treats them as unlike 
data sets). The indication must be made before the end of the current data set is 
reached. You must set bit 4 to | by using the instruction OI DCBOFLGS, X’08’ 
as described in Chapter 5, “Specifying a Data Control Block and Initializing 
Data Sets.” If bit 4 of the DCBOFLGS field 1s 1, end-of-volume processing for 
each data set will issue a close for the data set just read and an open for the next 
concatenated data set. This opening and closing procedure updates the fields in 
the DCB and, if necessary, builds a new IOB and a new channel program. If the 
buffer pool was obtained automatically by the open routine, the procedure also 
frees the buffer pool and obtains a new one for the next concatenated data set. 
The procedure does not issue a freepool for the last concatenated data set. 
Unless you have some way of determining the characteristics of the next data set 
eee before it is opened, you should not reset the DCBOFLGS field to indicate like 
( | attributes during processing. When you concatenate data sets with unlike 
attributes, no EOV exits are taken. 
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When unlike sequential data sets are concatenated, the GET or READ macro 
instruction that detected the end of data set’must be reissued. Figure 35 on 
page 114 illustrates a possible routine for determining when a GET or READ 
must be reissued. Also, you should not issue multiple input requests (that is, a 
series of READ or GET macros instructions) in your program. If you do, you 


will have to arrange some way to determine which requests have been completed 


and which must be reissued. These restrictions do not apply to like data sets, 
because no OPEN or CLOSE operation is necessary between data sets. 
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Figure 35. Reissuing a READ or GET for Unlike Concatenated Data Sets 
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When the change from one data set to another is made, label exits are taken as 


required; automatic volume switching is also performed for multiple volume data 
sets. Your end-of-data-set (EODAD) routine 1s not entered until the last data set 
has been processed. 


To save time when processing two consecutive sequential data sets on a single 
tape volume, you specify LEAVE in your OPEN macro instruction. 
Concatenated data sets cannot be read backward. — | 
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Processing with Chained Scheduling 


To accelerate the input/output operations required for a data set, the operating 
system provides a technique called chained scheduling. When requested, the 
system bypasses the normal I/O routines and dynamically chains several 
input/output operations together. A series of separate read or write operations, 
functioning with chained scheduling, is issued to the computing system as one 
continuous operation. In a nonpageable (V = R) address space, the 
program-controlled interruption (PCI) flag in the CCWs cause the PCI 
appendage to get control and dynamically chain the next I/O request to the 
currently executing channel program. 


The I/O performance is improved by reduction in both the processor time and 
the channel start/stop time required to transfer data within virtual storage. Some 
factors that affect performance improvement are: 

e Address space type (real or virtual) 

e¢ BUFNO for QSAM 

e The number of overlapped requests for BSAM (NCP) 

¢ Other activity on the processor and channel 

Chained scheduling can be used only with simple buffering. Each data set for 
which chained scheduling is specified must be assigned at least two and preferably 
more buffers with QSAM, or must have a value of at least two and preferably 
more for NCP with BSAM or BPAM. 

The system will default to chained scheduling for nondirect access devices (other 
than printers and format-U records on nondirect access devices), except for those 
cases in which it is not allowed. 

A request for exchange buffering in MVS/XA is not honored, but compatibly 
defaults to move mode and therefore has no effect on either a request for chained 


scheduling or a default to chained scheduling. 


A request for chained scheduling will be ignored and normal scheduling used if 
any of the following are encountered when the data set is opened: 


e CNTRL macro to be used. 

¢ Bypassing of embedded DOS checkpoint records on tape input. 

¢ Spooled data sets (SYSIN or SYSOUT). 

e NCP=1 or BUFNO=1 

e A print data set or any associated data set for the 3525 Card Punch. (For 
more information about programming the 3525, see OS and OS/VS 


Programming Support for the IBM 3505 Card Reader and IBM 3525 Card 
Punch.) 
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The number of channel program segments that can be chained 1s limited to the 
value specified in the NCP operand of BSAM DCBs, and to the value specified 
in the BUFNO operand of QSAM DCBs. 


When the data set is a printer, chained scheduling is not supported 
(DCB = OPTCD=C) when channel 9 or channel 12 is in the carriage control 
tape or FCB. 


When chained scheduling is being used, the automatic skip feature of the 
PRTOV macro for the printer will not function. Format control must be 
achieved by ANSI or machine control characters. (Control characters are 
discussed in more detail under “Carriage Control Character” on page 31, under 
“Record Format—Device Type Considerations” on page 28, and under 
Appendix B, “Control Characters” on page 213.) When you are using QSAM 
under chained scheduling to read variable-length, blocked, ASCII tape records 
(format-DB), you must code BUFOFF = L in the DCB for that data set. 


Note also that, if you are using BSAM with the chained scheduling option to 
read format-DB records and have coded a value for the BUFOFF operand other 
than BUFOFF = L, the input buffers will be converted from ASCII to EBCDIC 
as usual, but the record length returned to the DCBLRECL field will equal the 
block size, not the actual length of the record read in; the record descriptor word 
(RDW), if present, will not have been converted from ASCII to binary. 


Chained scheduling is most valuable for programs that require extensive input 
and output operations. Because a data set using chained scheduling may 
monopolize available time on a channel in a V=R region, separate channels 
should be assigned, if possible, when more than one data set is to be processed. 


Note: Chained scheduling is not a DASD option; it is built into the access 
method for DASD. 


Chained Scheduling Functions for DASD 


For direct access storage devices (DASD), chained scheduling is not supported. 
(If the chained scheduling option 1s specified for DASD, it is ignored.) Instead, 
the functions of chained scheduling are performed directly by the sequential 
access method (either BSAM or QSAM). 


In QSAM, the value of BUFNO determines how many channel programs or I/O 
requests will be chained together before I/O is initiated. The default value of 
BUFNO 1s 5; when five buffers are full (that is, five I/O requests have been 
issued), QSAM reads or writes all five records in a single revolution of the disk. 


In BSAM, the first READ or WRITE instruction initiates I/O. Subsequent I/O 
requests (without an associated CHECK or WAIT instruction) will be put in a 
queue, and the channel program associated with the request will be chained to 
the previous request in the queue. During channel end processing for the first 
I/O request, the queue is checked for pending I/O requests and the next request 
in the queue is started using the channel end appendage. The number of I/O 
requests that may be chained together is limited to the number of requests that 
can be handled in one I/O event (and one revolution of the disk) before channel 
end processing is complete. 
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( Search Direct for Input Operations 


To accelerate the input operations required for a data set on DASD, the 
operating system uses a technique called search direct. Search direct reads in the 
requested record and the count field of the next record. This allows the operation 
to get the next record directly, along with the count field of the following record. 


You may receive unpredictable results when your application has a dependency 
that is incompatible with the use of search direct. For example, you may receive 
unpredictable results when multiple DCBs are open for a file and one of the 
applications is adding records. 


Determining the Length of a Record on Input 


When you read a sequential data set, you can determine the length of the record 
in one of the following five ways, depending upon the record format of the data 
set: 


1. For fixed-length, unblocked records, the length of all records is the value in 
the DCBBLKSI field of the DCB. 


2. For variable-length records, the block descriptor word in the record contains 
the length of the record. 


( 3. For fixed-length blocked or undefined-length records, the following method 

| can be used to calculate the block length. This method can be used with 

| BSAM, BDAM, or BPAM. (This method should not be used when reading 
track overflow records or when using chained scheduling with format-U 
records. In these cases, the length of a record cannot be determined.) After 
checking the DECB for the READ request but before issuing any subsequent 
data management macros that specify the DCB for the READ request, 
obtain the IOB address from the DECB. The IOB address can be loaded 
from the location 16 bytes from the start of the DECB. 


Obtain the residual count from the channel status word (CSW) that has been 
3 stored in the input/output block (IOB). The residual count is in the 

| halfword, 14 bytes from the start of the IOB. For SYSIN or SYSOUT data 

| sets, the residual count can also be found in bytes 2 and 3 of the first word of 

| the DECB. Subtract this residual count from the number of data bytes 
requested to be read by the READ macro instruction. If 'S' was coded as 
the length parameter of the READ macro, the number of bytes requested is 
the value of DCBBLKSI at the time the READ was issued. If the length 
was coded in the READ macro, this value is the number of data bytes and it 
is contained in the halfword 6 bytes from the beginning of the DECB. The 
result of the subtraction is the length of the block read. See Figure 36 on 
page 118. 
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.. RECFM=U,NCP=2,... 


Figure 36. One Method of Determining the Length of the Record When Using BSAM to Read Undefined-Length 


Records 


4. When an undefined-length record is read, the actual length of the record 1s 
returned in the DCBLRECL field of the data control block. Because of this 
use of DCBLRECL, the LRECL operand should be omitted. This method 
can only be used with QSAM and BSAM. 


5. The length to be read or written can be supplied dynamically in a 
READ/WRITE macro using BSAM. This method cannot be used when 
using chained scheduling on any nondirect access device. 
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Writing a Short Block When Using the B3AM WRITE Macro 


If you have fixed-blocked record format, you can change the length of a block 
when you are writing blocks for a sequential data set. The DCB block size field 
(DCBBLKSJ) can be changed to specify a block size that is shorter than what 
was originally specified for the data set. The DCBBLKSI field must be changed 
before issuing the WRITE macro instruction and must be a multiple of the 
LRECL parameter in the DCB. Any subsequent WRITE macros issued will 
write records with the new block length until the block size is changed again. 
The DCB block size field should not be changed to specify a block size that is 
greater than what was originally specified for the data set. 


Managing SAM Buffer Space 


The operating system provides several methods of buffer acquisition and control. 
Each buffer (virtual storage area used for intermediate storage of input/output 
data) usually corresponds in length to the size of a block in the data set being 
processed. When you use the queued access technique, any reference to a buffer 
actually refers to the next record (buffer segment}. 


You can assign more than one buffer to a data set by associating the buffer with 
a buffer pool. A buffer pool must be constructed in a virtual storage area 
allocated for a given number of buffers of a given length. 


The number of buffers you assign to a data set should be a trade-off against the 
frequency with which you refer to each buffer. A buffer that is not referred to for 
a relatively long period of time may be paged out. If this were allowed to happen 
to any considerable degree, it could decrease throughput. 


Buffer segments and buffers within the buffer pool are controlled automatically 
by the system when the queued access technique is used. However, you can tell 
the system you are finished processing the data in a buffer by issuing a release 
(RELSE) macro for input or a truncate (TRUNC) macro instruction for output. 
The simple buffering technique can be used to process a sequential data set or an 
indexed sequential data set. | 


If you use the basic access technique, you can use buffers as work areas rather 
than as intermediate storage areas. You can control them directly, by using the 
GETBUF and FREEBUF macros, or dynamically for BDAM and BISAM, by 
requesting dynamic buffering in your DCB macro instruction and your READ or 
WRITE macro. If you request dynamic buffering, the system will automatically 
provide a buffer each time a READ macro is issued. That buffer will be freed 
when you issue a WRITE or FREEDBUF macro instruction. 
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Buffer Pool Construction if > 


‘ ; ‘ Ne / 
Buffer pool construction can be accomplished in any of three ways: 


e Statically, using the BUILD macro 
e Explicitly, using the GETPOOL macro 
e Automatically, by the system, when the data set is opened 


If QSAM simple buffering is used, the buffers are automatically returned to the 
pool when the data set is closed. If the buffer pool is constructed explicitly or 
automatically, the virtual storage area must be returned to the system by the 
FREEPOOL macro. 


In many applications, fullword or doubleword alignment of a block within a 
buffer is important. You can specify in the DCB that buffers are to start on 
either a doubleword boundary or a fullword boundary that is not also a 
doubleword boundary (by coding BFALN=D or F). If doubleword alignment is 
specified for format-V records, the fifth byte of the first record in the block is so 
aligned. For that reason, fullword alignment must be requested to align the first 
byte of the variable-length record on a doubleword boundary. The alignment of 
the records following the first in the block depends on the length of the previous 
records. 


Note that buffer alignment provides alignment only for the buffer. If records a 
from ISCII/ASCII magnetic tape are read and the records use the block prefix, x / 
the boundary alignment of logical records within the buffer depends on the length _ 
of the block prefix. If the length is 4, logical records are on fullword boundaries. 

If the length is 8, logical records are on doubleword boundaries. 


If the BUILD macro 1s used to construct the buffer pool, alignment depends on 
the alignment of the first byte of the reserved storage area. 


When you process multiple QISAM data sets, you can use a common buffer 
pool. To do this,. however, you must use the BUILD macro imstruction to. 
reformat the buffer pool before opening each data set. 


BUILD—Construct a Buffer Pool 


When you know, before program assembly, both the number and the size of the 
buffers required for a given data set, you can reserve an area of appropriate size to 
be used as a buffer pool. Any type of area can be used—for example, a 
predefined storage area or an area of coding no longer needed. 


A BUILD macro, issued during execution of your program, structures the 
reserved storage area into a buffer pool. The address of the buffer pool must be 
the same as that specified for the buffer pool control block (BUFCB) in your 
DCB. The buffer pool control block is an 8-byte field preceding the buffers in 
the buffer pool. The number (BUFNO) and length (BUFL) of the buffers must 
also be specified. The length of BUFL must be at least the block size. 
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When the data set using the buffer pool 1s closed, you can reuse the area as 
required. You can also reissue the BUILD macro to reconstruct the area into a 
new buffer pool to be used by another data set. 


You can assign the buffer pool to two or more data sets that require buffers of 
the same length. To do this, you must construct an area large enough to 
accommodate the total number of buffers required at any one time during 
execution. That is, if each of two data sets requires 5 buffers (BUFNO = 5), the 
BUILD macro should specify 10 buffers. The area must also be large enough to 
contain the 8-byte buffer pool control block. 


BUILDRCD— Build a Buffer Pool and a Record Area 


The BUILDRCD macro, like the BUILD macro, causes a buffer pool to be 
constructed in an area of virtual storage you provide. In addition, BUILDRCD 
makes it possible for you to access variable-length, spanned records as complete 
logical records, rather than as segments. 


You must be processing with QSAM in the locate mode and you must be 
processing either VS/VBS or DS/DBS records, if you want to access the 
variable-length, spanned records as logical records. If you issue the BUILDRCD 
macro before the data set is opened, or during your DCB exit routine, you 
automatically get logical records rather than segments of spanned records. 


Only one logical record storage area is built, no matter how many buffers are 
specified; therefore, you can’t share the buffer pool with other data sets that may 
be open at the same time. 


GETPOOL—Get a Buffer Pool 


If a specified area is not reserved for use as a buffer pool, or if you want to defer 
specifying the number and length of the buffers until execution of your program, 
you should use the GETPOOL macro instruction. It enables you to vary the 
size and number of buffers according to the needs of the data set being processed. 


The GETPOOL macro causes the system to allocate a virtual storage area to a 
buffer pool. The system builds a buffer pool control block and stores its address 
in the data set’s DCB. The GETPOOL macro should be issued either before 
opening of the data set or during your DCB’s OPEN exit routine. 


When using GETPOOL with QSAM, specify a buffer length (BUFL) at least as 
large as the block size. 


Automatic Buffer Pool Construction 


If you have requested a buffer pool and have not used an appropriate macro by 
the end of your DCB exit routine, the system automatically allocates virtual 
storage space for a buffer pool. The buffer pool control block is also assigned 
and the pool is associated with a specific DCB. For BSAM, a buffer pool is 
requested by specifying BUFNO. For QSAM, BUFNO can be specified or 
allowed to default to 5. If you are using the basic access technique to process an 
indexed sequential or direct data set, you must indicate dynamic buffer control. 
Otherwise, the system does not construct the buffer pool automatically. 
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Because a buffer pool obtained automatically is not freed automatically when you 
issue a CLOSE macro, you should also issue a FREEPOOL or FREEMAIN 


macro (discussed in the next section). 


F REEPOOL—F ree a Buffer Pool 





Any buffer pool assigned to a DCB either automatically by the OPEN macro 
(except when dynamic buffer control is used) or explicitly by the GETPOOL 
macro should be released before your program is terminated. The FREEPOOL 
macro should be issued to release the virtual storage area as soon as the buffers 
are no longer needed. When you are using the queued access technique, you 
| must close the data set first. If you are not using the queued access technique, it 
| is still advisable to close the data set first. 





If the OPEN macro was issued while running under a protect key of zero, a 
buffer pool that was obtained by OPEN should be released by issuing the 
FREEMAIN macro instead of the FREEPOOL macro. This is necessary 
because the buffer pool acquired under these conditions will be in storage 
assigned to subpool 252. 


Constructing a Buffer Pool 


Figure 37 and Figure 38 on page 123 illustrate several possible methods of 
constructing a buffer pool. They do not consider the method of processing or 
controlling the buffers in the pool. 


In Figure 37, a static storage area named INPOOL is allocated during program 
assembly. The BUILD macro, issued during execution, arranges the buffer pool 
into 10 buffers, each 52 bytes long. Five buffers are assigned to INDCB and 5 to 
OUTDCEB, as specified in the DCB macro for each. The two data sets share the 
buffer pool because both specify INPOOL as the buffer pool control block. 
) Notice that an additional 8 bytes have been allocated for the buffer pool to 
| : contain the buffer pool control block. The 4-byte chain pointer that occupies the 
| — first 4 bytes of the buffer 1s included 1 in the buffer, so no allowance need be made 


for this field. 
ers Processing 
BUILD INPOOL, 10,52 Structure a ities pool 
OPEN CINDCB, , OUTDCB, (OUTPUT) ) | 
piece | Processing 
ENDJOB CLOSE (INDCB, , OUTDCB) 
Sea — Processing 
| RETURN Return to system control 
INDCB DCB BUFNO=5, BUFCB=INPOOL, EODAD=ENDJOB, --- 
OUTDCB DCB _  BUFNO=5 , BUFCB=INPOOL, --- 
CNOP | 0,8 | Force boundary alignment 


INPOOL DS CL528 | Buffer pool 


Figure 37. Constructing a Buffer Pool from a Static Storage Area 


In Figure 38 on page 123, two buffer pools are constructed explicitly by the 
GETPOOL macros. Ten input buffers are provided, each 52 bytes long, to 
contain one fixed-length record; 5 output buffers are provided, each 112 bytes 
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long, to contain 2 blocked records plus an 8-byte count field (required by ISAM). 
Notice that both data sets are closed before the buffer pools are released by the 
FREEPOOL macros. The same procedure should be used if the buffer pools 
were constructed automatically by the OPEN macro. 


GETPOOL INDCB, 10,52 Construct a 10-buffer pool 
GETPOOL OUTDCB,5,112 Construct a 5-buffer pool 
OPEN (INDCB, , OUTDCB, (OUTPUT) ) 
ENDJOB CLOSE (INDCB, , OUTDCB) 
FREEPOOL INDCB Release buffer pools after all 


I/O is complete 
FREEPOOL OUTDCB 


RETURN Return to system control 
INDCB DCB DSORG=PS , BFALN=F , LRECL=52 , RECFM=F , EODAD=ENDJOB, --- 


OUTDCB DCB DSORG=IS, BFALN=D, LRECL=52 , KEYLEN=10 , BLKSIZE=104, C 
RKP=0 , RECFM=FB, --- 


Figure 38. Constructing a Buffer Pool Using GETPOOL and FREEPOOL 


Buffer Control 


Your program can use any of four techniques to control the buffers used by your 
program. The advantages of each depend to a great extent upon the type of job 
you are doing. Simple buffering is provided for the queued access technique. 
The basic access technique provides for either direct or dynamic buffer control. 


Although only simple buffering can be used to process an indexed sequential data 
set, buffer segments and buffers within a buffer pool are controlled automatically 
by the operating system. 


In addition, the queued access technique provides three processing modes that 
determine the extent of data movement in virtual storage. Move, data, and locate 
mode processing can be specified for either the GET or PUT macro. (Substitute 
mode 1s no longer supported; the system defaults to move mode.) The 
movement of a record is determined as follows: 


¢ Move mode— The record is moved from a system input buffer to your work 
area, or from your work area to an output buffer. 


¢ Data mode (QSAM format-V spanned records only )— The same as the move 
mode, except that only the data portion of the record is moved. 


e Locate mode— The record is not moved. Instead, the address of the next 
input or output buffer is placed in register 1. For QSAM format-V spanned 
records, if you have specified logical records by specifying BFTEK =A or by 
issuing the BUILDRCD macro, the address returned in register 1 points to a 
record area where the spanned record is assembled or segmented. 


The PUT-locate routine uses the value in the DCBLRECL field to determine 
whether another record will fit into your buffer. Therefore, when you write a 
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Simple Buffering 


short record, you can maximize the number of records per block by 
modifying the DCBLRECL field before you issue a PUT-locate to get a 
buffer segment for the short record. The processing sequence follows: ' 


1. Register 1 is returned to you with the address of the next buffer segment. 
2. Move the record into the output buffer segment. 

3. Put the length of the next (short) record into DCBLRECL. 

4. Issue PUT-locate. 

5. Move the short record into the buffer segment. 


e Substitute mode— Move mode is used when substitute mode is requested in 
MVS/XA. 


Two processing modes of the PUTX macro can be used in conjunction with a 
GET-locate macro. The update mode returns an updated record to the data set 
from which it was read; the output mode transfers an updated record to an 
output data set. There is no actual movement of data in virtual storage. The 
processing mode is specified by the operand of the PUTX macro, as explained in 
Data Administration: Macro Instruction Reference. 


If you use the basic access technique, you can control buffers in one of two ways: 


e Directly, using the GETBUF macro to retrieve a buffer constructed as 
described above. A buffer can then be returned to the pool by the 
FREEBUF macro. 


@ Dynamically, by requesting a dynamic buffer in your READ or WRITE 
macro. This technique can be used only when you are using BISAM or 
BDAM. If you request dynamic buffering, the system automatically provides 
a buffer each trme a READ macro is issued. The buffer is supplied from a 
buffer pool that is created by the system when the data set is opened. The 
buffer is released (returned to the pool) upon completion of a WRITE macro 
instruction when you are updating. If you do not update the record in the 
buffer and thus release the buffer without writing the record, the 
FREEDBUF macro may be used. If you are processing an indexed 
sequential data set, the buffer is automatically released upon the next issuance 
of the READ macro instruction if there has been no intervening WRITE or 
FREEDBUF macro. 


The term simple buffering refers to the relationship of segments within the buffer. 
All segments in a simple buffer are together in storage and are always associated 
with the same data set. When the buffer pool is constructed, the system creates a 
channel command word (CCW) for each buffer in the buffer pool. For this 
reason, each record must be physically moved from an input buffer segment to an 
output buffer segment. It can be processed within either segment or in a work 
area. 
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If you use simple buffering, records of any format can be processed. New records 
can be inserted and old records deleted as required to create a new data set. A 
record can be moved and processed as follows: 





¢ Processed in an input buffer and then moved to an output buffer 
(GET-locate, PUT-move/PUTX-output) 


e Moved from an input buffer to an output buffer where it can be processed 
(GET-move, PUT-locate) 


e Moved from an input buffer to a work area where it can be processed and 
then moved to an output buffer (GET-move, PUT-move) 


e Processed in an input buffer and returned to the same data set (GET-locate, 
PUTX-update) 


The following examples illustrate the control of simple buffers and the processing 
modes that can be used. The buffer pools may have been constructed in any way 
previously described. | 


Simple Buffering—GET-locate, PUT-move/PUTX-output: The GET macro (step 
A, Figure 39 on page 126) locates the next input record to be processed. Its 
address is returned in register 1 by the system. The address is passed to the PUT 
macro in register 0. 


( . The PUT macro (step B, Figure 39) specifies the address of the record in register 
0. The system then moves the record to the next output buffer. 


Note: The PUTX-output macro can be used in place of the PUT-move macro. 
However, processing will be as described under “Exchange Buffering” (see 
PUT-substitute). 


Simple Buffering—GET-move, PUT-locate: The PUT macro locates the address 
of the next available output buffer. Its address is returned in register 1 and is 
passed to the GET macro in register 0. 


The GET macro specifies the address of the output buffer into which the system 
moves the next input record. 


A filled output buffer is not written until the next PUT macro instruction is 
issued. 


Simple Buffering—GET-move, PUT-move: The GET macro (step A, Figure 40 
on page 126) specifies the address of a work area into which the system moves 
the next record from the input buffer. 
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OUTPUT OUTPUT 
PUT 
B OUTPUT OUTPUT 
Figure 39. Simple Buffering with MACRF=GL and MACRF = PM 
A OUTPUT | OUTPUT 
PUT i 
B 
Figure 40. Simple Buffering with MACRF=GM and MACRF=PM 
The PUT macro (step B, Figure 40) specifies the address of a work area from 
which the system moves the record into the next output buffer. 
e~ 
a 
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Simple Buffering—GET-locate, PUT-locate: The GET macro (step A, 
Figure 41) locates the address of the next available input buffer. The address is 
returned in register 1. 





| OUTPUT | OUTPUT | 
PUT 


| OUTPUT | OUTPUT | 















OUTPUT | 


| INPUT | INPUT 


Program 









Figure 41. Simple Buffering with MACRF= GL and MACRF = PL 


The PUT macro (step B, Figure 41) locates the address of the next available 
output buffer. Its address is returned in register 1. You must then move the 
record from the input buffer to the output buffer (step C, Figure 41). Processing 
can be done either before or after the move operation. 


A filled output buffer is not written until the next PUT macro instruction 1s 
issued. The CLOSE and FEOV macros write the last record of your data set by 
issuing TRUNC and PUT macro instructions. Be careful not to issue an extra 
PUT before issuing CLOSE or FEOV. Otherwise, when the CLOSE or FEOV 
macro tries to write your last record, the extra PUT will write a meaningless 
record or produce a sequence error. 


Simple Buffering—-UPDAT Mode: When a data set is opened with UPDAT 
specified (Figure 42 on page 128), only GET-locate and PUTX-update are 
supported. The GET macro locates the next input record to be processed and its 
address is returned in register 1 by the system. The user may update the record 
and issue a PUTX macro that will cause the block to be written back 1n its 
original location in the data set after all the logical records in that block have 
been processed. 
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Exchange Buffering 
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INPUT/ 
OUTPUT 
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(No movement of data takes place). 


Figure 42. Simple Buffering with MACRF=GL and MACRF=PM-UPDAT Mode | 


Exchange buffering is not supported in MVS/XA. Its request is ignored by the 
system and move mode is used instead. 


Buffering Techniques and GET/PUT Processing Modes 


As you can see from the previous examples, the most efficient code is achieved by 
use of automatic buffer pool construction, and GET-locate and PUTX-output 
with simple buffering. Figure 43 summarizes the combinations of buffering 
techniques and processing modes that can be used. 
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Figure 43. | Buffering Technique and GET/PUT Processing Modes 
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RELSE—Release an [nput Buffer 


When using the queued access technique to process a sequential or an indexed 
sequential data set, you can direct the system to ignore the remaining records in 
the input buffer being processed. The next GET macro retrieves a record from 
another buffer. If format-V spanned records are being used, the next logical 
record obtained may begin on any segment in any subsequent block. 


If you are using move mode, the buffer is made available for refilling as soon as 
the RELSE macro is issued. When you are using locate mode, the system does 
not refill the buffer until the next GET macro is issued. If a PUTX macro has 
been used, the block is written before the buffer is refilled. 


TRUNC—Truncate an Output Buffer 


When using the queued access technique to process a sequential data set, you can 
direct the system to write a short block. The first record in the next buffer is the 
next record processed by a PUT-output or PUTX-output mode. 


If the locate mode is being used, the system assumes that a record has been 
placed in the buffer segment pointed to by the last PUT macro. 


The last block of a data set is truncated by the close routine. Note that a data set 
containing format-F records with truncated blocks cannot be read from direct 
access storage as efficiently as a standard format-F data set. 


GETBUF—Get a Buffer from a Pool 


The GETBUF macro can be used with the basic access technique to request a 
buffer from a buffer pool constructed by the BUILD, GETPOOL, or OPEN 
macro. The address of the buffer is returned by the system in a register you 
specify when you issue the macro. If no buffer is available, the register contains a 
Q instead of an address. 


FREEBUF—Return a Buffer to a Pool 


The FREEBUF macro is used with the basic access technique to return a buffer 
to the buffer pool from which it was obtained by a GETBUF macro. Although 
the buffers need not be returned in the order in which they were obtained, they 
must be returned when they are no longer needed. 


FREEDBUF—Return a Dynamic Buffer to a Pool 


Any buffer obtained through the dynamic buffer option must be released before it 
can be used again. When you are processing a direct data set, if you do not 
update the block in the buffer and thus need to free the buffer instead of writing 
the block, you must use the FREEDBUF macro. If there is an uncorrectable 
input/output error, the control program releases the buffer. When you are | 
processing an indexed sequential data set, if you do not update the block in the 
buffer or, if there is an uncorrectable input error, the control program releases the 
buffer when the next READ macro 1s issued on the same DECB, unless you use 
the PRBEDBUF macro. 

_ 
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To effect the release, you must specify the address of the DECB that was used 
when the block was read using the dynamic buffering option and the address of 
the DCB associated with the data set being processed. 
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Chapter 10. Processing a Partitioned Data Set 


A partitioned data set is stored only on a direct access device. It is divided into 
sequentially organized members, each composed of one or more records (see 
Figure 44). Each member has a unique name, | to 8 characters long, stored in a 
directory that is part of the data set. The records of a given member are written 
or retrieved sequentially. 









: | \ 
Directory - 1 Entry for | Entry for 7 Entry for : Entry for 
Records | Member A | Member B | Member C | Member K_ | 


Space from 
Deleted 
Member 


Available 
Area 


Figure 44. A Partitioned Data Set 


The main advantage of using a partitioned data set is that, without searching the 
entire data set, you can retrieve any individual member after the data set is 
opened. For example, in a program library that is always a partitioned data set, 
each member is a separate program or subroutine. The individual members can 
be added or deleted as required. When a member ts deleted, the member name is 
removed from the directory, but the space used by the member cannot be reused 
until the data set is reorganized; that is, compressed using the IEBCOPY utility. 


The directory, a series of 256-byte records at the beginning of the data set, 
contains an entry for each member. Each directory entry contains the member 
name and the starting location of the member within the data set, as shown in 
Figure 44. In addition, you can specify as many as 62 bytes of information in 
the entry. The directory entries are arranged by name in alphameric collating 
sequence. 
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The starting location of each member is recorded by the system as a relative track 
address (from the beginning of the data set) rather than as an absolute track 
address. Thus, an entire data set that has been compressed, can be moved 
without changing the relative track addresses in the directory. The data set can 
be considered as one continuous set of tracks regardless of where the space was 
actually allocated. 


If there is not sufficient space available in the directory for an additional entry, or 
not enough space available within the data set for an additional member, or no 
room on the volume for additional extents, no new members can be stored. A 
directory can not be extended and a partitioned data set may not cross a volume 
boundary. 


Partitioned Data Set Directory 





Bytes 8 
Figure 45. A Partitioned Data Set Directory Block 


The directory of a partitioned data set occupies the beginning of the area 
allocated to the data set on a direct access volume. It is searched and maintained 
by the BLDL, FIND, and STOW macros. The directory consists of member 
entries arranged in ascending order according to the binary value of the member 
name or alias. 


Member entries vary in length and are blocked into 256-byte blocks. Each block 
contains as many complete entries as will fit in a maximum of 254 bytes; any 
remaining bytes are left unused and are ignored. Each directory block contains a 
2-byte count field that specifies the number of active bytes in a block (including 
the count field). As shown in Figure 45, each block is preceded by a 
hardware-defined key field containing the name of the last member entry in the 
block, that is, the member name with the highest binary value. 


Member 


Entry A 





Each member entry contains a member name or an alias. Each entry also 
contains the relative track address of the member and a count field, as shown in 
Figure 46 on page 133. In addition, it may contain a user data field. The last 
entry in the last directory block has a name field of maximum binary value—all 
l’s. 


132 MVS/XA Data Administration Guide 








a 














Pointer to 
First Record 
of Member 








ok 0-31 halfwords 
~ _ (Maximum 62 bytes) 
™ 


1 If Number of 
Name is an User Data 
Alias TTRNs 


Number of User 
Data Halfwords 





Bits 


Figure 46. A Partitioned Data Set Directory Entry 


NAME 


TTR 





specifies the member name or alias. It contains as many as 8 alphameric 
characters, left-justified, and padded with blanks if necessary. 


is a pointer to the first block of the member. TT is the number of the 
track, relative to the beginning of the data set, and R is the number of the 
block, relative to the beginning of that track. 


Note: This pointer is created by adding 1 to the TTR for the last block of 
the previous member (which is an end-of-file mark). If track TT is full, the 
next block will begin at record | of track TT + 1, and the pointer will be 
updated accordingly. The control program finds the block by searching in 
multitrack mode using TT(R-1) as a search argument. 


specifies the number of halfwords contained in the user data field. It may 
also contain additional information about the user data field, as shown 
below: 


Bits 0 1-2 3-7 


ee ee 


0 when set to 1, indicates that the NAME field contains an alias. 
1-2 specifies the number of pointers to locations within the member. 


The operating system supports a maximum of three pointers in the 
user data field. Additional pointers may be contained in a record 
referred to as a note list, discussed below. The pointers can be 
updated automatically if the data set is moved or copied by a utility 
program such as IEHMOVE. The data set must be marked 
unmovable under the following conditions: 
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e More than three pointers are used in the user data field. 


e The pointers in the user data field or note list do not conform to 
the standard format. 


Note: A note list for a partitioned data set containing variable 
length records does not conform to standard format. 


e Variable-length records contain BDWs and RDWs that are 
treated as TTRXs by IEHMOVE. 


e The pointers are not placed first in the user data field. 


e Any direct access address (absolute or relative) is embedded in 
any data blocks or in another data set that refers to this data set. 


3-7 contains a binary value indicating the number of halfwords of user 
data. This number must include the space used by pointers in the 
user data field. 


You can use the user data field to provide variable data as input to the STOW 
macro. If pointers to locations within the member are provided, they must be 4 
bytes long and placed first in the user data field. The user data field format is as 
follows: 


User Data 


Crew [tren [ten [ optionat | 


TT is the relative track address of the note list or area to which you are pointing. 
R 1s the relative block number on that track. 


N is a binary value that indicates the number of additional pointers contained 
in a note list pointed to by the TTR. If the pointer is not to a note list, 
N=0. 


A note list consists of additional pointers to blocks within the same member of a 
partitioned data set. You can divide a member into subgroups and store a 
pointer to the beginning of each subgroup in the note list. The member may be 
a load module containing many control sections (CSECTs), each CSECT being a 
subgroup pointed to by an entry in the note list. You get the pointer to the 
beginning of the subgroup by using the NOTE macro after you write the first 
record of the subgroup. Remember that the pointer to the first record of the 
member is stored in the directory entry by the system. 


If the existence of a note list was indicated as shown above, the list can be 


updated automatically when the data set is moved or copied by a utility program 
such as IEHMOVE. Each 4-byte entry in the note list has the following format: 
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TT 1s the relative track address of the area to which you are pointing. 
R _ is the relative block number on that track. 
X is available for any use. 


To place the note list in the partitioned data set, you must use the WRITE 
macro. After checking the write operation, use the NOTE macro to determine 
the address of the list and place that address in the user data field of the directory 
entry. 


Note: The linkage editor builds a note list for the load modules in overlay 
format. The addresses in the note list point to the overlay segments that-are read 
into the system separately. 


Allocating Space for a Partitioned Data Set 


What is the average size of the members to be stored on your direct access 
volume? How many members will fit on the volume? Will you need directory 
entries for the member names only or will aliases be used? How many? Will 
members be added or replaced frequently? All these questions must be answered 
if you are:to estimate your space requirements accurately and use the space 
efficiently. Note, too, that a partitioned data set cannot extend beyond one 
volume. 


If your data set will be large, or if you expect to update it extensively, it might be 
best to allocate a full volume. If it will be small or seldom subject to change, you 
should make your estimate as accurate as possible to avoid wasted space or 
wasted time used for re-creating the data set. 


If the average member length is close to or less than the track length or if the 
track length exceeds 32760 bytes, the most efficient use of the direct access 
storage space may be made with a block size of 1/3 or 1/2 the track length. For 
example, BLKSIZE = 23200 for a 3380 disk will yield two blocks per track. You 
might then ask for either 75 tracks, or 5 a thus allowing for 3480000 
bytes of data. 


Each member in a data set and each alias need one directory entry apiece. If you 
expect to have 10 members (10 directory entries) and an average of 3 aliases for 
each member (30 directory entries), allocate space for at least 40 directory entries. 


Assuming an average length of 70000 bytes for each member, you need space for 
at least 50 directory entries. If each member also has an average of three aliases, 
space for an additional 150 directory entries is required. 


Space for the directory is expressed in 256-byte blocks. Each block contains from 
3 to 21 entries, depending on the length of the user data field. If you expect 200 
directory entries, request at least 40 blocks. Any unused space on the last track 
of the directory is wasted unless there 1s enough space left to contain a block of 
the first member. 
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| Either of the following space specifications would cause the same size allocation Kec 
| for a 3380 disk; | - 
| SPACE=(CYL, (5, ,10)) 
| SPACE=(TRK, (75, ,10)) 
The following example would result in allocation of 100 tracks for data, plus 1 


track for directory space: 


SPACE=( 23200, (100, ,10)) 


Although a secondary allocation increment has been omitted in these examples, it 
could have been supplied to provide for extension of the member area. The 
directory size, however, cannot be extended. 


Creating a Partitioned Data Set 


If you have no need to add entries to the directory, that is, the STOW macro will 
not be used, you can create a new data set and write the first member as follows 
(see Figure 47): 


® Code DSORG= PS or DSORG= PSU in the DCB macro. 

e Indicate in the DD statement that the data is to be stored as a member of a 
new partitioned data set, that is, DS NAME= name (membername) and cee 
DISP = NEW. | 

¢ Request space for the member and the directory in the DD statement. 

e Process the member with an OPEN macro, a series of PUT or WRITE 
macros, and then a CLOSE macro instruction. A STOW macro 1s issued 


automatically when the data set is closed. 


As a result of these steps, the data set and its directory are created, the records of 
the member are written, and a 12-byte entry is made in the directory. 


| //PDSDD DD — ---,DSNAME=MASTFILE(MEMBERK) , SPACE=(TRK,(100,5,7)), 
| DISP=(NEW, CATLG) , DCB=(RECFM=FB , LRECL=80 , BLKSIZE=80) --- 


OPEN (OUTDCB, (OUTPUT)) 


PUT  OUTDCB,OUTAREA Write record to member 
CLOSE (OUTDCB) , Automatic STOW 
OUTAREA DS CL80 Area to write from 


| OUTDCB DCB ---,DSORG=PS , DDNAME=PDSDD , MACRF=PM 


Figure 47. Creating One Member of a Partitioned Data Set __ | a 
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To add additional members to the data set, follow the same procedure. However, 
a separate DD statement (with the space request omitted) is required for each 
member. The disposition should be specified as modify, DISP= MOD. The 
data set must be closed and reopened each time a new member is specified on the 
DD statement. 


To take full advantage of the STOW macro, and thus the BLDL and FIND 
macros, in future processing, you can provide additional information with each 
directory entry. You do this by using the basic partitioned access technique, 
which also allows you to process more than one member without closing and 
reopening the data set, as follows (see Figure 48 on page 138). | 


Request space in the DD statement for the entire data set and the directory. 
Define DSORG= PO or DSORG= POU 1n the DCB macro. 
Use WRITE and CHECK to write and check the member records. 


Use NOTE to note the location of any note list written within the member, 
if there is a note list, or to note the location of subgroups if there are any. 


When all the member records have been wnitten, issue a STOW macro 
instruction to enter the member name, its location pointer, and any 
additional data in the directory. The STOW macro writes an end-of-file 
mark after the member. 


Continue to write, check, note, and stow until all the members of the data set 
and the directory entries have been written. 
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ce emamemamnainarad 





//PDSDD DD 


OPEN 
LA 


~--, DSN=MASTFILE , DISP=MOD, SPACE=(TRK, (100,5,7)) 


(OUTDCB, (OUTPUT) ) 
STOWREG,STOWLIST Load address of STOW list 


**% WRITE MEMBER RECORDS AND NOTE LIST 


MEMBER WRITE 
CHECK 
LA 


WRITE 
CHECK 


NOTE 
ST 

LA 
WRITE 
CHECK 
NOTE 


oT 
STOW 


LA 


DECBX,SF,OUTDCB,OUTAREA WRITE first record of member 
DECBX 
NOTEREG,NOTELIST Load address of NOTE list 


DECBY,SF,OUTDCB,OUTAREA WRITE and CHECK next record 
DECBY 


OUTDCB To divide the member into subgroups, 


R1, OCNOTEREG) NOTE the TIRN of the first record in 
the subgroup, storing it in the 
NOTE list. : 


NOTEREG,4(NOTEREG) Increment to next NOTE list entry 


DECBZ,SF,OUTDCB,NOTELIST WRITE NOTE list record at the 
end of the member 


DECBZ 
OUTDCB NOTE TTRN of NOTE list record 
R1, 12(STOWREG) Store TTRN in STOW list 


OUTDCB,(STOWREG),A Enter the information in directory 
for this member after all records 
and NOTE lists are written. 

STOWREG, 16(STOWREG) Increment to the next STOW list entry 


Repeat from label ”"MEMBER” for each additional member | 


olla 
ae 


CLOSE 
OUTAREA DS 
OUTDCB DCB 


Rl EQU - 
NOTEREG EQU 
NOTELIST DS 
DS 
DS 
STOWREG EQU 
STOWLIST DS 
DC 
DS 
DC 
DS 


( OUTDCB ) (NO automatic STOW) 


CL80 Area to write from 
~--, DSORG=PO , DDNAME=PDSDD , MACRF=W 
iL. | Register one, return register from NOTE 


4 Register to address NOTE list 

OF NOTE list 

F NOTE list entry (4 byte TTRN) 

19F one entry per subgroup | 

5 Register to address STOW list 

OF List of member names for STOW 
CL8'MEMBERA' Name of member | 

CL3 TTR of first record (created by STOW) 
x23" C byte, 1 user TTRN, 4 bytes of user data 
CL4 TTRN of NOTE list 


one list entry per member (16 bytes each) 


Figure 48. Creating Members of a Partitioned Data Set Using STOW 
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( Processing a Member of a Partitioned Data Set 


Because a member of a partitioned data set is sequentially organized, it is 
processed in the same manner as a sequential data set. Either the basic or 
queued access technique can be used. However, you cannot alter the directory 
when using the queued technique. 


To locate a member or to process the directory, several macros are provided by 
the operating system. The BLDL macro can be used to read one or more 
directory entries into virtual storage; the FIND macro locates a member of the 
data set and positions the DCB for subsequent processing; the STOW macro 
adds, deletes, replaces, or changes a member name in the directory. To use these 
macros, you must specify DSORG= PO or POU in the DCB macro. Before 
issuing FIND, BLDL, or STOW macro, you must check all preceding 
input/output operations for completion. 


BLDL—Construct a Directory Entry List 


The BLDL macro reads one or more directory entries into virtual storage. The 

member names are placed in a BLDL list that is constructed before the BLDL 

macro is issued. For each member name in the list, the system supplies the 

address of the member and any additional information contained 1n the directory 

entry. Note that, if there is more than one member name in the list, the member 

names must be in collating sequence, regardless of whether the members are from 
( ~~ the same library or from different libraries. 


You can optimize retrieval time by directing a subsequent FIND macro 
instruction to the BLDL list rather than to the directory to locate the member to 
be processed. | 


The BLDL list, as shown in Figure 49 on page 140, must be preceded by a 
4-byte list description that indicates the number of entries in the list and the 
length of each entry (12 to 76 bytes). The first 8 bytes of each entry contain the 
member name or alias. The next 6 bytes contain the TTR, K, Z, and C fields. 
If there is no user data entry, only the TTR and C fields are required. If 
additional information is to be supplied from the directory, as many as 62 bytes 
can be reserved. | | 


FIND—Position to a Member 


To determine the starting address of a specific member, you must issue a FIND 
macro. The system places the correct address in the data control block so that a 
subsequent input or output operation begins processing at that point. 


There are two ways you can direct the system to the nght member when you use 
the FIND macro. Specify the address of an area containing the name of the 
member or specify the address of the TTR field of the entry in a BLDL list you 
have created by using the BLDL macro. In the first case, the system searches the 
directory of the data set for the relative track address; in the second case, no 
search is required, because the relative track address 1s in the BLDL list entry. 
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(Each entry starts on halfword boundary) 


Filled in by BLDL 
C 
(1 1 (1) 


Loeb 
auitcuel 
im 
| | 


List 
Description 










User Data 
(C Halfwords) 


Programmer supplies: 
FF Number of member entries in list. 
LL Even number giving byte length of each entry (minimum of 12). 
Member name _— Eight bytes, left-justified. 


BLDL supplies: 
TTR Member starting location. 
\ K If single data set = 0. If concatenation = number. 

Not required if no user data. 

Z Source of directory entry. Private library = 0. 
Link library = 1. Job or step library = 2. 
Not required if no user data. 

C Same C field from directory. Gives number of user data halfwords. 

‘ User data As much as will fit in entry. 


Figure 49. BLDL List Format 





The system will also search a concatenated series of directories when (1) a DCB 
is supplied that is opened for a concatenated partitioned data set or (2) a DCB 1s 
not supplied, in which case either JOBLIB or STEPLIB (themselves perhaps 
concatenated) followed by LINKLIB 1s searched. 


If you want to process only one member, you can process it as a sequential data 
set (DSORG= PS) using either BSAM or QSAM. You indicate the name of the 
member you want to process and the name of the partitioned data set in the 
DSNAME parameter of the DD statement. When you open the data set, the 
system places the starting address in the data control block so that a subsequent 
GET or READ macro begins processing at that point. You cannot use the 
FIND, BLDL, or STOW macro when you are processing one member as a 
sequential data set. 


Because the DCBRELAD address in the data control block is updated when the 
FIND macro is used, you should not issue the FIND macro after WRITE and 
STOW processing without first closing the data set and reopening it for INPUT 
processing. | 
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STOW — Update the Directory 





When you add more than one member to a partitioned data set, you must issue a 
STOW macro after writing each member so that an entry for each one will be 
added to the directory. To use the STOW macro, DSORG= PO or POU must 
be specified in the DCB macro. 


| You can also use the STOW macro to delete, replace, or change a member name 

| in the directory and store additional information with the directory entry. 
Because an alias can also be stored in the directory the same way, you should be 
consistent in altering all names associated with a given member. For example, if 
you replace a member, you must delete related alias entries or change them so 
that they point to the new member. An alias cannot be stored in the directory 
unless the member is present. 


If you add only one member to a partitioned data set and indicate the member 
name in the DSNAME parameter of the DD statement, it is not necessary for 
you to use BPAM and a STOW macro in your program. If you want to do so, 
you may use BPAM and STOW, or BSAM or QSAM. If you use a sequential 
access method, or if you use BPAM and issue a CLOSE macro without issuing a 
STOW macro, the system will issue a STOW macro instruction using the 
member name you have specified on the DD statement. When the system issues 
the STOW, the directory entry that is added is the minimum length (12 bytes). 
This automatic STOW macro will not be issued if the CLOSE macro 1s a 
TYPE=T or if the TCB indicates the task is being abnormally terminated when 

a the DCB is being closed. The DISP parameter on the DD statement determines 

( what directory action parameter will be chosen by the system for the STOW 

macro. 


If DISP= NEW or MOD was specified, a STOW macro with the add option will 
be issued. If the member name on the DD statement is not present in the data 
set directory, it will be added. If the member name is already present in the 
directory, the task will be abnormally terminated. 


If DISP = OLD was specified, a STOW macro with the replace option will be 
issued. The member name will be inserted into the directory, either as an 
addition, if the name is not already present, or as a replacement, 1f the name 1s 
present. 


Thus, with an existing data set, you should use DISP= OLD to force a member 


into the data set; you should use DISP= MOD to add members with protection 
against the accidental destruction of an existing member. 


Retrieving a Member of a Partitioned Data Set 


To retrieve a specific member from a partitioned data set, either the basic or the 
queued access technique can be used as follows (see Figure 50 on page 142): 


e Code DSORG= PS or DSORG= PSU in the DCB macro. 
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e Indicate in the DD statement that the data is a member of an existing co 
partitioned data set by coding DSNAME=name(membername) and y 


DISP = OLD. a 
@ = =Process the member with an OPEN macro, a series of GET and READ 
macros, and then a CLOSE macro instruction. 
//PDSDD DD ---, DSN=MASTFILE(MEMBERK) , DISP=OLD 
OPEN (CINDCB) Open for input, automatic FIND 
GET  INDCB,INAREA Read member record 
CLOSE (INDCB) 
INAREA DS CL80 Area to read into 
INDCB DCB ~--, DSORG=PS , DDNAME=PDSDD , MACRF=GM 
Figure 50. Retrieving One Member of a Partitioned Data Set 
¢ When your program is executed, the directory is searched automatically and the 
location of the member is placed in the DCB. 
To process several members without closing and reopening, or to take advantage _ 
of additional data in the directory, this technique should be used (see Figure 51): 4 


¢ Code DSORG= PO or POU in the DCB macro. 


e Indicate in the DD statement the data set name of the partitioned data set by 
coding DSNAME= name and DISP= OLD. 


e Issue the BLDL macro to get the list of member entries you need from the 
directory. 


e Use the FIND or POINT macro to prepare for reading the member records. 

e The records may be read from the beginning of the member, or a note list 
may be read first, to obtain additional locations that point to subcategories 
within the member. 

e Read (and check) the records until all those required have been processed. 

e Point to additional categories, if required, and read the records. 

e Your end-of-data-set (EODAD) routine receives control at the end of each 
member. At that time, you can process the next member or close the data 


set. 


e Repeat this procedure for each member to be retrieved. 
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//PDSDD 





DD ---, DSN=MASTFILE, DISP=OLD 


OPEN (INDCB) Open for input, no automatic FIND 


LA BLDLREG,BLDLLIST Load address of BLDL list 

BLDL INDCB,BLDLLIST Build a list of selected member 
names in virtual storage 

LA BLDLREG, 4(BLDLREG) Point to the first entry 


Read the NOTE list 


MEMBER 


Od 
ca) 


LA NOTEREG,NOTELIST Load address of NOTE list 
MVC TTRN(4),14(BLDLREG) Move NOTE list TTRN 

to fullword boundary 
POINT INDCB,TTRN Point to the NOTE list record 
READ DECBX,SF, INDCB, (NOTEREG) | Read the NOTE list 
CHECK DECBX : 


Read data from a subgroup 


SUBGROUP 


POINT INDCB, (NOTEREG) Point to subgroup - 

READ DECBY,SF,INDCB,INAREA Read record in subgroup 
CHECK DECBY 7 

LA NOTEREG,4(NOTEREG) Increment to next subgroup TTRN 


Repeat from label “SUBGROUP” for each additional subgroup 
Repeat from label “MEMBER?” for each additional member 


INAREA 
INDCB 
TIRN 
NOTEREG 
NOTELIST 


BLDLREG 
BLDLLIST 


Figure 51. 


CLOSE (INDCB) 


DS CL80 

DCB ---, DSORG=PO, DDNAME= PDSDD; MACRF=R 

DS F TTRN of the NOTE list to point at 
EQU) 4 Register to: address NOTE list entries 
DS OF NOTE list — | 

DS F NOTE list entry (4 byte TTRN) 

DS 19F one entry per subgroup 

EQU 5 Register to address BLDL list entries 
DS OF List of member names for BLDL | 

DC H'10° Number of entries (10 for example) 

DC H'18' Number of bytes per entry 

DC CL8'MEMBERA' Name of member LoS 

DS CL3 TTR of first record (éfadted by BLDL) 
DS xX K byte, concatenation number — 

DS xX Z byte, location code ~ 

DS X C byte, flag and user data leawth 


DS CL4 TTRN of NOTE list 
bass one list entry per member (18 eo each) 


Retrieving Several Members and i Sabavougs of a Partitioned Data Set 
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Modifying a Partitioned Data Set ) os 





Updating a Member of a Partitioned Data Set 


Updating in Place 


A member of a partitioned data set can be updated in place, or it can be deleted 
and rewritten as a new member. 


When you update in place, you read records, process them, and write them back 
to their onginal positions without destroying the remaining records on the track. 
The following rules apply: 





e You must specify the update option (UPDAT) in the OPEN macro 
instruction. To perform the update, you can use only the READ, WRITE, 
CHECK, NOTE, POINT, FIND, and BLDL macros. 


e You cannot update concatenated partitioned data sets. 


e You cannot use chained scheduling. 


' @ You cannot delete any record or change its length; you cannot add new 


records. 


A record must be retrieved by a READ macro before it can be updated by a 
WRITE macro. Both macros must be execute forms that refer to the same 
DECB; the DECB must be provided by a list form. (The execute and list forms 
of the READ and WRITE macros are described in Data Administration: Macro 
Instruction Reference.) 


Updating with OSAM: You can update a member of a partitioned data set using 
the locate mode of QSAM (DCB specifies MACRFE = PL) and using the PUTX 
macro. The DD statement must specify the data set and member name in the 
DSNAME parameter. This method allows only the updating of the member 
specified in the DD statement. 


Updating with Overlapped Operations: ‘To overlap input/output and processor 
activity, you can start several read or write operations before checking the first for 
completion. You cannot overlap read and write operations, however, as 
operations of one type must be checked for completion before operations of the 
other type are started or resumed. Note that each outstanding read or write 
operation requires a separate channel program and a separate DECB. If a single 
DECB were used for successive read operations, only the last record read could 
be updated. | 


In Figure 52 on page 145, overlap is achieved by having a read or write request 
outstanding while each record is being processed. Note the use of the execute 
and list forms of the READ and WRITE macros, identified by the operands 
MF=E and MF=L. 7 
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//PDSDD DD 


UPDATDCB DCB 
READ 
READ 
AREAA DS 
AREAB DS 
OPEN 
LA 
LA 
READRECD READ 
NEXTRECD READ 
CHECK 





DSNAME=MASTFILE(MEMBERK) , DISP=OLD, --- 


DSORG=PS , DDNAME=PDSDD , MACRF=(R,W) , NCP=2 , EODAD=F INISH 
DECBA, SF, UPDATDCB , AREAA, MF=L Define DECBA 
DECBB, SF, UPDATDCB , AREAB , MF=L Define DECBB 


Define buffers 


(If update is required, branch to RRUPDATE) 


LR 
LR 
LR 
B 


(UPDATDCB, UPDAT ) Open for update 

2,DECBA Load DECB addresses 

3, DECBB 

(2) ,SF,MF=E Read a record 

(3),SF,MF=E Read the next record 

(2) Check previous read operation 
4,3 If no update is required, 

D2 switch DECB addresses in 

2,4 registers 2 and 3 

NEXTRECD and loop | 


In the following statements, 'R2' and "R3" refer to the records that were read using the DECBs whose 
addresses are in registers 2 and 3, respectively. Either register may point to either DECBA or DECBB. 


R2UPDATE CALL 
CHECK 
WRITE 


UPDATE, ((2)) Call routine to update R2 
(3) Check read for next record 
(2),SF,MF=E (R3) Write updated R2 


(If R3 requires an update, branch to RSUPDATE) 


CHECK 


B 

R3UPDATE CALL 
WRITE 
CHECK 
CHECK 
B 

FINISH CLOSE 


(2) If R3 requires no update, 
READRECD check write for R2 and loop 
UPDATE, ((€3)) Call routine to update R3 
(3),SF,MF=E Write updated R3 

(2) Check write for R2 

(3) Check write for R3 

READRECD Loop 


(UPDATDCB ) End-of-Data exit routine 


Figure 52. Updating a Member of a Partitioned Data Set 


Rewriting a Member 


There is no actual update option that can be used to add or extend records in a 
partitioned data set. If you want to extend or add a record within a member, you 
must rewrite the complete member in another area of the data set. Because space 
is allocated when the data set is created, there is no need to request additional 
space. Note, however, that a partitioned data set must be contained on one 
volume. If sufficient space has not been allocated, the data set must be 
reorgamzed by the IEBCOPY utility program. 


When you rewrite the member, you must provide two DCBs, one for input and 


one for output. Both DCB macros can refer to the same data set, that is, only 
one DD statement 1s required. 
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You can reflect the change in location of the member either automatically, by ot 
indicating a disposition of OLD, or by using the STOW macro. Although the | Re 
old member is, in effect, deleted, its space cannot be reused until the data set is 
reorganized. 


If an out-of-space condition occurs when updating a PDS member, the error 
recovery procedure will STOW the PDS member as ‘TEMPNAME’. The 


original member will remain intact. 


Processing a Partitioned Data Set Residing on MSS 


If OPTCD = H 1s specified in the DCB subparameter of a DD statement, it 
specifies that, if a partitioned data set is being opened for input and resides on an 
MSS device, then at OPEN tume the data set is staged to EOF on the virtual 
DASD device. If the option is not specified, only the directory is staged at 
OPEN time and cylinder faults occur during processing. This option might be 
used with the IEBCOPY utility program opening the PDS to reorganize and 
compress the data space. This BPAM option, OPTCD= H, may only be coded 
on the DD statement. | 


Concatenating Partitioned Data Sets 


Two or more partitioned data sets can be automatically retrieved by the system 
and processed successively as a single data set. This reading technique is known | 
as concatenation. Data sets with like characteristics are those that may be Me 
processed correctly using the same data control block (DCB), input/output block 

(IOB), and channel program. Any exception makes them unlike. 


Partitioned Concatenation 


When partitioned data sets are concatenated, the system treats the group as a 
single data set and only one data extent block (DEB) is constructed. The 
maximum number of partitioned data sets that can be concatenated 1s 123 extents 
(input data sets only). For example, 123 single extent data sets can be 
concatenated but 8 data sets each with 16 extents cannot be concatenated. 


Concatenated partitioned data sets are always treated as having like attributes and 
use the attributes of the first data set only. 


You process a concatenation of partitioned data sets the same way you process a 

single partitioned data set with one exception: you must use the FIND macro to 

begin processing a member; you cannot use the POINT (or NOTE) macro until 

after the FIND macro has been issued. Figure 51 on page 143 shows how to 

process a’single partitioned data set using FIND. If two members of different 

data sets in the concatenation have the same name, the FIND macro determines 

the address of the first one in the concatenation. You would not be able to 

process the second one in the concatenation. The BLDL macro provides the 

concatenation number of the data set to which the member belongs in the K field > 
of the BLDL list. (See “BLDL—Construct a Directory Entry List” on ; 
page 139.) | | | 
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Reading a BPAM Directory Sequentially 


You can read a BPAM directory sequentially just by opening the data set to its 
beginning (without using positioning macros) and reading it. 


e The DD statement should identify the DSNAME without a member name. 
You should specify a disposition option of either OLD or SHR. 


e You can use either BSAM or QSAM with MACRF=R or G. 
e Specify BLKSIZE = 256 and RECFM=F. 
e You must test for the last directory entry (X’FFFFFFFP’). 


e If you also want to read the keys (the name of the last member in that 
block), use BSAM and specify KEYLEN = 8. 
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Chapter 11. Processing a Direct Data Set 


In a direct data set, there is a relationship between a control number or 
identification of each record and its location on the direct access volume. This 
relationship allows you to gain access to a record without an index search. You 
determine the actual organization of the data set. If the data set has been 
carefully organized, location of a particular record takes less time than with an 
indexed sequential data set. 


The DSORG parameter of the DCB macro specifies the type of processing to be 
performed; DSORG in the DD statement specifies the organization of the data 
set when it is created. 


Although you can process a direct data set sequentially using either the queued 
access technique or the basic access technique, you cannot read record keys using 
the queued access technique. When you use the basic access technique, each unit 
of data transmitted between virtual storage and an I/O device is regarded by the 
system as a record. If, in fact, it is a block, you must perform any blocking or 
deblocking required. For that reason, the LRECL field is not used when 
processing a direct data set. Only BLKSIZE must be specified when you read, 
add, or update records on a direct data set. 


If dynamic buffering is specified for your direct data set, the system will provide a 
buffer for your records. If dynamic buffering is not specified, you must provide a 
buffer for the system to use. | 


As indicated in the discussion of direct access devices, record keys are optional. If 
they are specified, they must be used for every record and must be of a fixed 
length. 


Direct Data Set Organization 





In developing the organization of your data set, you can use direct addressing. 
When direct addresses are used, the location of each record in the data set is 
known. 


If format-F records with keys are being written, the key of each record can be 
used to identify the record. For example, a data set with keys ranging from 0 to 
4999 should be allocated space for 5000 records. Each key relates directly to a 
location that you can refer to as a relative record number. Therefore, each record 
should be assigned a unique key. If identical keys are used, it is possible, during 
periods of high processor and channel activity, to skip the desired record and 
retrieve the next record on the track. The main disadvantage of this type of 
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organization is that records may not exist for many of the keys even though space 
has been reserved for them. 


Space could be allocated on the basis of the number of records in the data set 
rather than on the range of keys. This type of organization requires the use of a 
cross-reference table. When a record is written in the data set, you must note the 
physical location as a relative block number, an actual address, or as a relative 
track and record number. The addresses must then be stored in a table that is 
searched when a record 1s to be retrieved. Disadvantages are that 
cross-referencing can be used efficiently only with a small data set, storage 1s 
required for the table, and processing time is required for searching and updating 
the table. 


A more common, but somewhat complex, technique for organizing the data set 
involves the use of indirect addressing. In indirect addressing, the address of each 
record in the data set is determined by a mathematical manipulation of the key. 
This manipulation is referred to as randomizing or conversion. Because a 
number of randomizing procedures could be used, no attempt is made here to 
describe or explain those that might be most appropriate for your data set. 


Creating a Direct Data Set 
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After the organization of a direct data set has been determined, the process of 
creating it is almost identical to that of creating a sequential data set. The BSAM 
DCB macro should be used with the WRITE macro instruction (the form used 
to create a direct data set). The following parameters must be specified in the 
DCB macro instruction: 


e DSORG= PS or PSU 
e¢ DEVD=DA or omitted 
e MACRF=WL 


The DD statement must indicate direct access (DSORG= DA or DAU). If keys 
are used, a key length (KEYLEN) must also be specified. Record length 
(LRECL) need not be specified but may be used to provide compatibility with 
sequential access method processing of this data set. 


It is possible to create a direct data set using QSAM (no keys allowed) or BSAM 
(with or without keys and the DCB specifies MACRF=W). However, this 
method is not recommended because, when you access this direct data set, you 
cannot request a function that requires the information in the capacity record 
(RO) data field. For example, the following restrictions would apply: 


e Variable-length, undefined-length, or variable-length spanned record 
processing is not allowed. 


e The WRITE add function with extended search for fixed-length records (with 
or without track overflow) 1s not allowed. 
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If a VIO data set is opened for processing with the extended search option, the 
DEBENDCC and DEBENDHH fields of the DEB will reflect the real address of 
the last record wntten during the BDAM create step. This prevents BDAM from 
searching unused tracks. The information needed to determine the data set size 1s 
written in the DSCB during the close of the DCB used 1n the create step. 
Therefore, if this data set is being created and processed by the same program, 
and the DCB used for creating the data set has not been closed before opening 
the DCB to be used for processing, the resultant beginning and ending CCHH 
will be equal. 


If a direct data set is created and updated or read within the same job step, and 
the OPTCD parameter is used in the creation, updating, or reading of the data 
set, different DCBs and DD statements should be used. 


If you are using direct addressing with keys, you can reserve space for future 
format-F records by writing a dummy record. To reserve or truncate a track for 
format-U, format-V, or format-VS records, write a capacity record. The capacity 
record (RO) contains a 7-byte data field (CCHHRLL), where CCHHR is the ID 
of the last record on the track, and LL is the number of unused bytes on the 
track. Ifa WRITE SZ macro is issued for a track with no records, R is zero and 
LL is the entire length of the track. 


Format-F records are written sequentially as they are presented. When a track 1s 
filled, the system automatically writes the capacity record and advances to the 
next track. Because of the form in which relative track addresses are recorded, 
direct data sets whose records are to be identified by means other than actual 
address must be limited in size to no more than 65 536 tracks for the entire data 
Set. 


Tape-to-Disk—Direct Data Set: In the example problem in Figure 53 on 


page 152, a tape containing 204-byte records arranged in key sequence is used to 


create a direct data set. A 4-byte binary key for each record ranges from 1000 to 
8999, so space for 8000 records is requested. 
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//DAOUTPUT DD 
//TAPINPUT DD 


DIRECT 


NEXTREC 
COMPARE 


DUMMY 


INPUTEND 
ENDJOB 


DUMAREA 
DALOAD 


TAPEDCB 


BLKSIZE=200 , KEYLEN=4 , RECFM=F ) , SPACE=( 204, 8000), --- 


START 
we 
OPEN 
LA 
GET 


LR 
C 


BNE 
WRITE 
CHECK 
AH 

B 

C 

BH 
WRITE 
CHECK 
AH 

BR 

LA 


BR 
CLOSE 
DS” 
DCB 
DCB 


DSNAME=SLATE . INDEX. WORDS , DCB=(DSORG=DA, 


9,=F'1000' 

(DALOAD , (OUTPUT) , TAPEDCB ) 

10, COMPARE 

TAPEDCB 

2.1 

9,0(2) Compare key of input against 
control number 

DUMMY 

DECB1,SF,DALOAD, (2) 

DECB1 

9,=H'1' 

NEXTREC 

9,=F'8999' Have 8000 records been written? 

ENDJOB 

DECB2,SD,DALOAD , DUMAREA 

DECB2 

9,=H'1' 

10 

10 , DUMMY 


10 
(TAPEDCB, , DALOAD) 


8F 

DSORG=PS , MACRF=(WL) , DDNAME=DAOUTPUT, 
DEVD=DA, SYNAD=CHECKER, aie 
EODAD=INPUTEND sMACRE=(GL), - 


Write data record 


Write dummy 


Figure 53. Creating a Direct Data Set 


Referring to a Record in a Direct Data Set 


After you have determined how your data set 1s to be organized, you must 
consider how the individual records will be referred to when the data set 1s 
updated or new records are added. The record neon can be represented 


in any of the following forms: 


Relative Block Address: You specify the relative location of the record (block) 
within the data set as a 3-byte binary number. This type of reference can be used 
only with format-F records. The system computes the actual track and record 


number. The relative block address of the first block is 0. 


Relative Track Address: You specify the relative track as a 2-byte binary 
number and the actual record number on that track as a 1-byte binary number. 


The relative track address of the first track 1s 0. 


152 MVS/XA Data Administration Guide 


Y ‘. 
: \, 
' 














Relative Track or Block Address and Actual Key: In addition to the relative 
track or block address, you specify the address of a virtual storage location 
containing the record key. The system computes the actual track address and 
searches for the record with the correct key. 


Actual Address: You supply the actual address in the standard 8-byte 
form—MBBCCHHR. Remember that the use of an actual address may force 
you to indicate that the data set is unmovable. 


Extended Search: You request that the system begin its search with a specified 
starting location and continue for a certain number of records or tracks. This 
same option can be used to request a search for unused space where a record can 


be added. | 


To use the extended search option, you must indicate in the DCB (DCBLIMCT) 
the number of tracks (including the starting track) or records (including the 
starting record) that are to be searched. If you indicate a number of records, the 
system may actually examine more than this number. In searching a track, the 
system searches the whole track (starting with the first record); it therefore may 
examine records that precede the starting record or follow the ending record. 


If the DCB specifies a number equal to or greater than the number of tracks 
allocated to the data set or the number of records within the data set, the entire 
data set is searched in the attempt to satisfy your request. 


Exclusive Control for Updating: \When more than one task 1s referring to the 
same data set, exclusive control of the block being updated is required to prevent 
simultaneous reference to the same record. Rather than issuing an ENQ macro 
each time you update a block, you can request exclusive control through the 
MACRF field of the DCB and the type operand of the READ macro. The 
coding example in Figure 55 on page 156 illustrates the use of exclusive control. 
After the READ macro is executed, your task has exclusive control of the block 
being updated. No other task in the system requesting access to the block is 
given access until the operation started by your WRITE macro is complete. If, 
however, the block is not to be written, you can release exclusive control using 
the RELEX macro. 


Feedback Option: ‘This option specifies that the system is to provide the address 
of the record requested by a READ or WRITE macro. This address may be in 
the same form that was presented to the system in the READ or WRITE macro, 
or as an 8-byte actual address. This option can be specified in the OPTCD 
parameter of the DCB and in the READ or WRITE macro. If this option is 
omitted from the DCB but is requested in a READ or WRITE macro, an 8-byte 


- actual address 1s returned to the user. 


The feedback option is automatically provided for a READ macro instruction 
requesting exclusive control for updating. This feedback will be in the form of an 
actual address (MBBCCHHR) unless feedback was specified in the OPTCD field 
of the DCB. In this case, feedback is returned in the format of the addressing 
scheme used in the problem program (an actual or a relative address). When a 
WRITE or RELEX macro is issued (which releases the exclusive control that 
was gotten for the READ request), the system will assume that the addressing 
scheme used for the WRITE or RELEX macro is in the same format as the 
addressing scheme used for feedback in the READ macro. 
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Adding or Updating Records on a Direct Data Set 


The techniques for adding records to a direct data set depend on the format of 
the records and the organization used. 


Format-F With Keys: Adding a record amounts to essentially an update by 
record identification. The reference to the record can be made by either a relative 
block address or a relative track address. 


If you want to add a record passing a relative block address, the system converts 
the address to an actual track address. That track is searched for a dummy 
record, and if one is found the new record is written.in place of it. If there is no 
dummy record on the track, you are informed that the write operation did not 
take place. If you request the extended search option, the new record will be 
written in place of the first dummy record found within the search limits you 
specify. If none is found, you are notified that the write operation could not take 
place. In the same way, a reference by relative track address causes the record to 
be written in place of a dummy record on the referenced track or the first within 
the search limits, if requested. If extended search is used, the search begins with 
the first record on the track. Without extended search, the search may start at 
any record on the track. Therefore, records that were added to a track are not 
necessarily located on the track in the same sequence they were written in. 


Format-F Without Keys: Were too, adding a record is really updating a dummy 
record already in the data set. The main difference is that dummy records cannot 
be written automatically when the data set is created. You will have to use your 
own method for flagging dummy records. The update form of the WRITE 
macro (MACRF=W) must be used rather than the add form (MACRF= WA). 


You will have to retrieve the record first (using a READ macro instruction), test 
for a dummy record, update, and write. 


Format-V or Format-U With Keys: The technique used to add records 1n this 
case depends on whether records are located by indirect addressing or a 
cross-reference table. If indirect addressing is used, you must at least initialize 
each track (write a capacity record) even if no data 1s actually written. That way 
the capacity record indicates how much space 1s available on the track. Ifa 
cross-reference table is used, you should exhaust the input and then initialize 
enough succeeding tracks to contain any additions that might be required. 


To add a new record, use a relative track address. The system examines the 
capacity record to see if there is room on the track. If there is, the new record is 
written. Under the extended search option, the record is written 1n the first 
available area within the search limit. 


Format-V or Format-U Without Keys: Because a record of this type does not 
have a key, you can access the record only by its relative track or actual address 
(direct addressing only). When you add a record to this data set, you must retain 
the relative track or actual address data (for example, by updating your 
cross-reference table). The extended search option is not allowed because it 
requires keys. 
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/ /DIRADD 
//TAPEDD 


DIRECTAD 


NEXTREC 


DD 
DD 


START 
OPEN 
GET 

L 

SH 

ST 
WRITE 
WAIT 


CLC 
BE 








Tape-to-Disk Add—Direct Data Set: The example in Figure 54 on page 155 


involves adding records to the data set created in the last example. Notice that 


the write operation adds the key and the data record to the data set. If the 


existing record is not a dummy record, an indication 1s returned in the exception 
code of the DECB. For that reason, it is better to use the WAIT macro instead 


of the CHECK macro to test for errors or exceptional conditions. 


DSNAME=SLATE. INDEX.WORDS, --- 


(DIRECT, (OUTPUT) , TAPEIN) 
TAPEIN, KEY 
4, KEY 
4,=H'1000' 
4,REF 
DECB, DA, DIRECT, DATA, 'S' , KEY, REF+1 
ECB=DECB 

DECB+1(2) ,=X'0000' 
NEXTREC 


Set up relative record number 


Check for any errors 


Check error bits and take required action 


DIRECT — 


TAPEIN 
KEY 
DATA 
REF 


DCB 


DCB 
DS 
DS 
DS 


DDNAME=DIRADD , DSORG=DA, RECFM=F , KEYLEN=4 , BLKSIZE=200, 
MACRF=(WA) 


F 
CL200 
F 


Figure 34. Adding Records to a Direct Data Set 


Tape-to-Disk Update—Direct Data Set: The example in Figure 55 is similar to 
that in Figure 54, but involves updating rather than adding. There is no check 
for dummy records. The existing direct data set contains 25000 records whose 
5-byte keys range from 00001 to 25000. Each data record is 100 bytes long. The 
first 30 characters are to be updated. Each input tape record consists of a 5-byte 
key and a 30-byte data area. Notice that only data is brought into virtual storage 


for updating. 


When you are updating variable-length records, you should use the same length 


to read and wnite a record. 
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//DIRECTDD DD DSNAME=SLATE. INDEX. WORDS, --- 
//TAPINPUT DD --- 
DIRUPDAT START 
OPEN (DIRECT, (UPDAT) , TAPEDCB) 
NEXTREC GET TAPEDCB, KEY 
PACK KEY, KEY 
CVB 3, KEYFIELD 
SH 3,=H'1' 
ST 3,REF 
READ DECBRD,DIX,DIRECT,'S','S',0,REF+1 
CHECK  DECBRD 
iv 3, DECBRD+12 
MVC 0(30,3),DATA 
ST 3, DECBWR+12 
WRITE DECBWR,DIX,DIRECT,'S','S',0,REF+1 
CHECK DECBWR 
B NEXTREC 
KEYFIELD DS OD 
DC XL3'0' 
KEY DS CL5 
DATA DS CL30 
REF DS F 
DIRECT DCB DSORG=DA , DDNAME=DIRECTDD , MACRF=(RISXC,WIC), C 


OPTCD=RF , BUFNO=1, BUFL=100 
TAPEDCB DCB == 


Figure 55. Updating a Direct Data Set 


Consideration for User Labels: User labels, if wanted, must be created when the 
data set is created. They may be updated, but not added or deleted, during 
processing of a direct data set. When creating a multivolume direct data set using 
BSAM, you should turn off the header exit entry after OPEN and turn on the 
trailer label exit entry just before issuing the CLOSE. This eliminates the 
end-of-volume exits. The first volume, containing the user label track, must be 
mounted when the data set is closed. If you have requested exclusive control, 
OPEN and CLOSE will ENQ and DEQ to prevent simultaneous reference to 
user labels. 


Consideration for using the 2305-2 Fixed Head Storage: When a data set on a 
2305-2 device is to be used by several tasks simultaneously, or when overlapping 
I/O (successive writes issued without an intervening CHECK or WAIT) ts used, 
the following combination may produce overlaying of records: 


e WRITE-add processing 


e Fixed records with or without track overflow 
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Sharing Direct Data Sets 


BDAM permits several tasks to share the same DCB and several jobs to share 
the same data set. It synchronizes I/O requests at both levels by maintaining a 
read-exclusive list. 


‘When several tasks share the same DCB and each asks for exclusive control of 
the same block, BDAM issues a system ENQ for the block (or in some cases the 
whole track). It reads in the block and passes it to the first caller while putting 
all subsequent requests for that block on a wait queue. When the first task 
releases the block, BDAM moves it into the next caller’s buffer and posts it 
complete. The block is passed to subsequent callers in the order the request was 
received. 


BDAM not only synchronizes the I/O requests, but also issues only one ENQ 
and one I/O request for several read requests for the same block. 


Note: Because BDAM processing 1s not sequential and I/O requests are not 
related, a caller can continue processing other blocks while waiting for exclusive 
control of the shared block. | 


Because BDAM issues a system ENQ for each record held exclusively, it allows a 
data set to be shared between jobs, so long as all callers use BDAM. BDAM’s 
commonly understood argument is what is enqueued on. 


BDAM supports multiple task users of a single DCB when working with existing 
data sets. When operating in load mode, however, only one task may use the 
DCB at a time. The following restrictions and comments apply when more than 
one task shares the same DCB, or when using multiple DCBs for the same data 
set. 


e Subpool 0 must be shared. 


e The user should ensure that a WAIT or CHECK macro has been issued for 
all outstanding BDAM requests before the task issuing the READ or 
WRITE macro terminates. In case of abnormal termination, this can be 
done through a STAE/STAI or ESTAE exit. 


¢ FREEDBUF and/or RELEX macros should be issued to free any resources 
that could still be held by the terminating task. This can be done during or 


after task termination. 


Note: Open, close, and all I/O must be performed in the same key and state 
(problem state or supervisor state). 
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Chapter 12. Processing an Indexed Sequential Data Set 


The organization of an indexed sequential data set allows you a great deal of 
flexibility in the operations you can perform. The data set can be read or written 
sequentially, individual records can be processed in any order, records can be 
deleted, and new records can be added. The system automatically locates the 
proper position in the data set for new records and makes any necessary 
adjustments when records are deleted. 


The queued access technique must be used to create an indexed sequential data 
set. It can also be used to sequentially process or update the data set and to add 
records to the end of the data set. The basic access technique can be used to 
insert new records between records already in the data set and to update the data 
set directly. 


Indexed Sequential Data Set Organization 





The records in an indexed sequential data set are arranged according to collating 
sequence by a key field in each record. Each block of records is preceded by a 
key field that corresponds to the key of the last record in the block. 


An indexed sequential data set resides on direct access storage devices and can 
occupy as many as three different areas: 


e Prime Area—This area, also called the prime data area, contains data records 
and related track indexes. It exists for all indexed sequential data sets. 


e Overflow Area—This area contains records that overflow from the prime area 
when new data records are added. It is optional. 


e Index Area—This area contains master and cylinder indexes associated with 
the data set. It exists for a data set that has a prime area occupying more 
than one cylinder. 


The indexes of an indexed sequential data set are analogous to the card catalog in 
a library. For example, if you know the name of the book or the author, you 
can look in the card catalog and obtain a catalog number that will enable you to 
locate the book in the book files. You then go to the shelves and proceed 
through rows until you find the shelf containing the book. Usually each row 
contains a sign to indicate the beginning and ending numbers of all books in that 
particular row. Thus, as you proceed through the rows, you compare the catalog 
number obtained from the index with the numbers posted on each row. Upon 
locating the proper row, you search that row for the shelf that contains the book. 
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Then you look at the individual book numbers on that shelf until you find the € 


panicles book. 
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ISAM uses the indexes in much the same way to iceaic records in an indexed 


sequential data set. 


As the records are written in the prime area of the data set, the system accounts 
for the records contained on each track in a track index area. Each entry in the 
track index identifies the key of the last record on each track. There is a track 
index for each cylinder in the data set. If more than one cylinder is used, the 
system develops a higher-level index called a cylinder index. Each entry in the 
cylinder index identifies the key of the last record in the cylinder. To increase the 
speed of searching the cylinder index, you can request that a master index be 
developed for a specified number of cylinders, as shown in Figure 56. 


Rather than reorganize the whole data set when records are added, you can 
request that space be allocated for additional records in an overflow area. 


Prime Area 


Records are written in the prime area when the data set is created or updated. 

The last track of prime data is reserved for an end-of-file mark. The portion of 

Figure 56 labeled Cylinder 1 illustrates the initial structure of the prime area. 

Although the prime area can extend across several noncontiguous areas of the 

volume, all the records are written in key sequence. Each record must contain a | | 
key; the system automatically writes the key of the highest record before each ee | 


block. 
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When the ABSTR option of the SPACE parameter of the DD statement 1s used 
to generate a multivolume prime area, the VOC of the second volume and on 
all succeeding volumes must be contained within cylinder 0 of the volume. 


The operating system generates track and cylinder indexes automatically. As 
many as three levels of master index are created if requested. 


This is the lowest level of index and is always present. There is one track index 
for each cylinder in the prime area; it is written on the first track(s) of the cylinder 
that it indexes. 


The index consists of a series of paired entries, that is, of a normal entry and an 
overflow entry for each prime track. For fixed-length records, each normal entry 
(and also DCBFIRSH) points to either record 0 or the first prime record on a 
shared track (a track shared by index and data). For variable-length records, the 
normal entry contains the key of the highest record on the track and the address 
of the last record on the track. The overflow entry is originally the same as the 
normal entry. (This is why 100 appears twice on the track index for cylinder 1 in 
Figure 56.) The overflow entry is changed when records are added to the data 
set. Then the overflow entry contains the key of the highest overflow record and 
the address of the lowest overflow record logically associated with the track. 
Figure 57 on page 162 shows the format of a track index. 


If all the tracks allocated for the prime data area are not used, the index entries 
for the unused ones are flagged as inactive. The last entry of each track index is a 
dummy entry indicating the end of the index. When fixed-length record format 
has been specified, the remainder of the last track of each cylinder used for a track 
index contains prime data records 1f there is room for them. 
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Normal key = key of the highest record on the prime data track 


2Normal data address of the prime data track 


key of the highest overflow record logically associated with the prime data track 


i 


3 Qverflow key 


2 Overtiaw data = address of the lowest overfidw record logically associated with the prime data track 


Notes: 
@ if there are no overflow records, overflow key and data entries are the same as normal key and data entries. 
@ This figure is a logical representation only; that is, it makes no attempt to show the physical size of track index entries. 
Figure 57. Format of Track Index Entries 
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Each index entry has the same format as the others. It is an unblocked, . 2 
fixed-length record consisting of a count, a key, and a data area. The length of | 
the key corresponds to the length of the key area in the record to which it points. 

The data area is always 10 bytes long. It contains the full address of the track or 

record to which the index points, the level of the index, and the entry type. 


Cylinder Index 


For every track index created, the system generates a cylinder index entry. There 
is one cylinder index for a data set that points to a track index. Because there is 
one track index per cylinder, there is one cylinder index entry for each cylinder in 
the prime data area, except in the case of a 1-cylinder prime area. As with track 
indexes, inactive entries are created for any unused cylinders in the prime data 
area. 


Master Index 


As an optional feature, the operating system creates, at your request, a master 
index. The presence of this index makes long, serial searches through a large, 
cylinder index unnecessary. | 


You can specify the conditions under which you want a master index created. 
For example, if you have specified NTM=3 and OPTCD=M in your DCB 
macro, a master index is created when the cylinder index exceeds 3 tracks. The 
master index consists of one entry for each track of cylinder index. If your data 
set is extremely large, a higher-level master index is created when the first-level 
master index exceeds three tracks. This higher-level master index consists of one 
entry for each track of the first-level master index. This procedure can be 
repeated for as many as three levels of master index. 
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Overflow Areas 





As records are added to an indexed sequential data set, space is required to 
contain those records that will not fit on the prime data track on which they 
belong. You can request that a number of tracks be set aside as a cylinder 
overflow area to contain overflows from prime tracks in each cylinder. An 
advantage of using cylinder overflow areas is a reduction of search time required 
to locate overflow records. A disadvantage is that there will be unused space if 
the additions are unevenly distributed throughout the data set. 


Instead of, or in addition to, cylinder overflow areas, you can request an 
independent overflow area. Overflow from anywhere in the prime data area is 
placed in a specified number of cylinders reserved solely for overflow records. An 
advantage of having an independent overflow area is a reduction in unused space 
reserved for overflow. A disadvantage is the increased search time required to 
locate overflow records in an independent area. 


If you request both cylinder overflow and independent overflow, the cylinder 
overflow area is used first. It is a good practice to request cylinder overflow areas’ 
large enough to contain a reasonable number of additional records and an 
independent overflow area to be used as the cylinder overflow areas are filled. 


Creating an Indexed Sequential Data Set 


You can create an indexed sequential data set in one step or in several steps. 

You can create the data set either by writing all records in a single step or by 
writing one group of records in one step and writing additional groups of records 
in subsequent steps. Writing records in subsequent steps is called resume loading. 
When using either one step or several steps, you must present the records for 
writing in ascending order by key. 


To create an indexed sequential data set by the one-step method, you should 
proceed as follows: 


¢ Code DSORG=IS or DSORG=ISU and MACREF=PM or MACRF= PL 
in the DCB macro. 


e Specify in the DD statement the DCB attributes DSORG=IS or 
DSORG= ISU, record length (LRECL), blocksize (BLKSIZE), record 
format (RECFM), key length (KEYLEN), relative key position (RKP), 
options required (OPTCD), cylinder overflow (CYLOFL), and the number 
of tracks for a master index (NTM). Specify space requirements with the 
SPACE parameter. To reuse previously allocated space, omit the SPACE 
parameter and code DISP=(OLD, KEEP). | 


¢ Open the data set for output. 


e Use the PUT macro to place all the records or blocks on the direct access 
volume. 


® Close the data set. 
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The records that comprise a newly created data set must be presented for writing 
in ascending order by key. You can merge two or more input data sets. If you 
want a data set with no records (a null data set), you must write at least one 
record when you create the data set. You can subsequently delete this record to 
achieve the null data set. 


If an unload is done that deletes all existing records in an ISAM data set, at least 
one record must be written on the subsequent load. If no record is written, the 
data set will be unusable. 


If the records are blocked, you should not write a record with a hexadecimal 
value of FF and a key of hexadecimal value FF. This value is used for padding. 
If it occurs as the last record of a block, the record cannot be retrieved. If the 
record is moved to the overflow area, it is lost. 


When creating an indexed sequential data set, a procedure called loading, you can 
improve performance by using the full-track-index write option. You do this by 
specifying OPTCD= U in the DCB. This causes the operating system to 
accumulate track index entries in virtual storage. Note that the full-track-index 
write option can be used only for fixed-length records. 


If you do not specify full-track-index write, the operating system writes each 
normal overflow pair of entries for the track index after the associated prime data 
track has been written. If you do specify full-track-index write, the operating 
system accumulates track index entries in virtual storage until either (a) there are 
enough entries to fill a track or (b) end-of-data or end-of-cylinder is reached. 
Then the operating system writes these entries as a group, writing one group for 
each track of track index. This option requires allocation of more storage space 
(the space in which the track index entries are gathered), but the number of I/O 
operations required to write the index can be significantly decreased. 


When you specify the full-track-index write option, the track index entnes are 
written as fixed-length unblocked records. If the area of virtual storage available 
is not large enough the entries are written as they are created, that 1s, in normal 
overflow pairs. 


After an indexed sequential data set has been created, its characteristics cannot be 
changed. However, for added flexibility, the system allows you to retrieve records 
by using either the queued access technique with simple buffering or the basic 
access technique with dynamic buffering. 


Tape-to-Disk—Indexed Sequential Data Set: The example in Figure 58 on 

page 165 shows the creation of an indexed sequential data set from an input tape 
containing 60-character records. The key by which the data set is organized is in 
positions 20 through 29. The output records will be an exact image of the input, 
except that the records will be blocked. One track per cylinder 1s to be reserved 
for cylinder overflow. Master indexes are to be built when the cylinder index 
exceeds 6 tracks. Reorganization information about the status of the cylinder 
overflow areas is to be maintained by the system. The delete option will be used 
during any future updating. 
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//INDEXDD DD DSNAME=SLATE . DICT( PRIME) , DOCB=( BLKSI ZE=240 , CYLOFL=1, C 
// DSORG=IS , OPTCD=MYLR , RECFM=FB , LRECL=60 , NIM=6 , RKP=19, C 

KEYLEN=10) , UNIT=3330 , SPACE=(CYL, 25, , CONTIG), --- 
//INPUTDD DD =S= 


ISLOAD START 0 
DCBD DSORG=IS 


ISLOAD CSECT 
OPEN (IPDATA, , ISDATA, (OUTPUT) ) 


NEXTREC GET IPDATA Locate mode 
LR 0,1 Address of record in register 1 
PUT ISDATA, (0) Move mode 
B NEXTREC 
CHECKERR L 3 ,=ACISDATA) Initialize base for errors 
USING IHADCB,3 
™ DCBEXCD1, X'04' 
BO OPERR Uncorrectable error 
™ DCBEXCD1, X'20' 
BO NOSPACE Space not found 
TM DCBEXCD2, X' 80' 
BO SEQCHK Record out of sequence 


Rest of error checking 
Error routine 
End of job routine (EODAD FOR IPDATA) 


pets IPDATA DCB aes 
( ISDATA DCB DDNAME=INDEXDD , DSORG=IS , MACRF=( PM) , SYNAD=CHECKERR 


Figure 58. Creating an Indexed Sequential Data Set 


To create an indexed sequential data set in more than one step, create the first 
group of records using the one-step method described above. This first section 
must contain at least one data record. The remaining records can then be added 
to the end of the data set in subsequent steps, using resume load. Each group to 
be added must contain records with successively higher keys. This method allows 
you to create the indexed sequential data set in several short time periods rather 
than in a single long one. 


This method also allows you to provide limited recovery from uncorrectable 
output errors. When an uncorrectable output error is detected, do not attempt to 
continue processing or to close the data set. If you have provided a SYNAD 
routine, it should issue the ABEND macro to terminate processing. If no 
SYNAD routine is provided, the control program will terminate your processing. 
If the error shows that space in which to add the record was not found, you must 
close the data set; issuing subsequent PUT macros can cause unpredictable 
results. You should begin recovery at the record following the end of the data as 
of the last successful close. The rerun time is limited to that necessary to add the 
new records, rather than to that necessary to re-create the whole data set. 


When you extend an indexed sequential data set with resume load, the 
disposition parameter of the DD statement must specify MOD. To ensure that 
the necessary control information is in the DSCB before attempting to add 
records, you should at least open and close the data set successfully on a version 
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of the system that includes resume load. This is necessary only if the data set was 
created on a previous version of the system. Records may be added to the data eee 
set by resume load until the space allocated for prime data in the first step has 

been filled. 


During resume load on a data set with a partially filled track and/or a partially 
filled cylinder, the track index entry and/or the cylinder index entry is overlaid 
when the track or cylinder is filled. Resume load for variable-length records 
begins at the next sequential track of the prime data set. If resume load 
abnormally terminates after these index entries have been overlaid, a subsequent 
resume load will result in a sequence check when it adds a key that is higher than 
the highest at the last successful CLOSE but lower than the key in the overlaid 
index entry. When the SYNAD exit is taken for a sequence check, register 0 
contains the address of the high key of the data set. However, if the SYNAD exit 
is taken during CLOSE, register 0 will contain the IOB address. 


Allocating Space for an Indexed Sequential Data Set 


An indexed sequential data set has three areas: prime, index, and overflow. Space 
for these areas can be subdivided and allocated as follows: 


e Prime area—If you request a prime area only, the system automatically uses a 
portion of that space for indexes, taking one cylinder at a time as needed. 
Any unused space in the last cylinder used for index will be allocated as an 
independent overflow area. More than one volume can be used in most | 
cases, but all volumes must be for devices of the same device type. ed 


@ Index area—You can request that a separate area be allocated to contain your 
cylinder and master indexes. The index area must be contained within one 
volume, but this volume can be on a device of a different type than the one 
that contains the prime area volume. If a separate index area is requested, 
you cannot catalog the data set with a DD statement. 


If the total space occupied by the prime area and index area does not exceed 
one volume, you can request that the separate index area be embedded in the 
prime area (to reduce access arm movement) by indicating an index size in 
the SPACE parameter of the DD statement defining the prime area. 


If you request space for prime and index areas only, the system automatically 
uses any space remaining on the last cylinder used for master and cylinder 
indexes for overflow, provided the index area is on a device of the same type 
as the prime area. 


¢ Overflow area—Although you can request an independent overflow area, it 
must be contained within one volume and must be of the same device type as 
the prime area. If no specific request for index area is made, then it will be 
allocated from the specified independent overflow area. 





166 MVS/XA Data Administration Guide 











To request that a designated number of tracks on each cylinder be used for 
cylinder overflow records, you must use the CYLOFL parameter of the DCB 
macro. The number of tracks that you can use on each cylinder equais the 
total number of tracks on the cylinder minus the number of tracks needed for 
track index and for prime data, that 1s: 


Overflow tracks = total tracks 
- (track index tracks + prime data tracks) 


Note that, when you create a I-cylinder data set, ISAM reserves | track on the 
cylinder for the end-of-file filemark. You may not request an independent index 
for an ISAM data set that has only | cylinder of prime data. 


When you request space for an indexed sequential data set, the DD statement 
must follow a number of conventions, as shown below and summarized in 
Figure 59 on page 167. 


@ Space can be requested only in cylinders, SPACE =(CYL,(...)), or absolute 
tracks, SPACE = (ABSTR,(...)). If the absolute track technique is used, the 
designated tracks must make up a whole number of cylinders. 


e Data set organization (DSORG) must be specified as indexed sequential (IS 
or ISU) in both the DCB macro and the DCB parameter of the DD 
statement. 


@ All required volumes must be mounted when the data set is opened; that is, 
volume mounting cannot be deferred. 


e If your prime area extends beyond one volume, you must indicate the 
number of units and volumes to be spanned; for example, 
UNIT = (3380,3), VOLUME = (,,,3). 


e You can catalog the data set using the DD statement parameter 
DISP= (,CATLG) only if the entire data set is defined by one DD statement; 
that is, if you did not request a separate index or independent overtlow area. 


As your data set is created, the operating system builds the track indexes in the 
prime data area. Unless you request a separate index area or an embedded index 
area, the cylinder and master indexes are built in the independent overflow area. 
If you did not request an independent overflow area, the cylinder and master 
indexes are built in the prime area. 


If an error is encountered during allocation of a multivolume data set, the 
IEHPROGM utility program should be used to scratch the DSCBs of the data 
sets that were successfully allocated. The IEHLIST utility program can be used 
to determine whether or not part of the data set has been allocated. The 
IEHLIST utility program is also useful to determine whether space is available or 
whether identically named data sets exist before space allocation is attempted for 
indexed sequential data sets. These utility programs are described in Utilities. 
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Criteria 






_ | Restrictions on 
| Unit Types and 
| of DD Number of Units | 
| Statements | | Requested Resulting Arrangement of Areas 
Separate index, prime, and overflow 


TINDEX_| 'None | 
PRIME | 
{OVFLOW | _ _ 


areas. 
| Separate index and prime areas. Any 
partially used index cylinder is used for 
independent overflow if the index and 
prime areas are on the same type of 
eAbods | 












| 1. Number | 2. Types 
| of DD 


, Statements 































PRIME Yes 


| OVFLOW 


Prime area and =p index, and 
overflow area. 


| The statement 
| defining the 
prime area 
cannot request 
more than one 
unit. 


m 


Yes Statement 
cannot request 
more than one 
unit. 










Prime area with index at its end. Any 
partially used index cylinder is used for 
independent. overflow. 






















Prime area with embedded index area; 
independent overflow in remainder of 
| partially used index cylinder. 





Figure 59. Requests for Indexed Sequential Data Sets 


Specifying a Prime Data Area 


To request that the system allocate space and subdivide it as eared, you should 


code: 


//ddname DD DSNAME=dsnane, DCB=DSORG=IS, 
// SPACE=(CYL, quantity, ,CONTIG), UNIT=unitname, 
// DISP=(, KEEP), “<= 


You can accomplish the same type of allocation by qualifying your dsname with 
the element indication (PRIME). This element is assumed if omitted. It is 
required only if you request an independent index or overflow area. To request 
an embedded index area when an independent overflow area is specified, you 
must indicate DSNAME=dsname (PRIME). To indicate the size of the 
embedded index, you specify SPACE = (CYL,(quantity,,index size)). 
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Specifying a Separate Index Area 


To request a separate index area, other than an embedded area as described 


- above, you must use a separate DD statement. The element name is specified as 


(INDEX). The space and unit designations are as required. Notice that only the 
first DD statement can have a data definition name. The data set name (dsname) 
must be the same. 


//ddname DD DSNAME=dsname( INDEX), --- 
i DD DSNAME=dsname( PRIME) ,--- 


Specifying an Independent Overflow Area 


A request for an independent overflow area is essentially the same as for a 
separate index area. Only the element name, OVFLOW,, 1s changed. If you do 
not request a separate index area, only two DD statements are required. 


//ddname DD DSNAME=dsname( INDEX), --- 
// DD DSNAME=dsname(PRIME),--- 
// DD DSNAME=dsname(OVFLOW),--~-- 


Calculating Space Requirements for an Indexed Sequential Data Set 


To determine the number of cylinders required for an indexed sequential data set, 
you must consider the number of blocks that will fit on a cylinder, the number of 
blocks that will be processed, and the amount of space required for indexes and 
overflow areas. When you make the computations, consider how much 
additional space is required for device overhead. Figure 68 on page 219 and 
Figure 69 on page 220 show device capacities and overhead formulas. In the 
formulas that follow, the length of the last (or only) block, shown below as Bn, 
must include device overhead as given in Figure 69. 


Blocks = Track capacity / Length of blocks 


The following eight steps summarize calculation of space requirements for an 
indexed sequential data set. 


Note: Use modulo-32 arithmetic when calculating key length and data length 
terms in your equations. Compute these terms first, then round up to the nearest 
increment of 32 bytes before completing the equation. 


Step I; After you know how many records will fit on a track and the maximum 
number of records you expect to create, you can determine how many tracks you 
will need for your data. 


Number of = (Maximum number of blocks 
tracks required / Blocks per track) + 1 


ISAM load mode reserves the last prime data track for the file mark. 


Example: Assume that a 200000 record parts-of-speech dictionary 1s stored on an 
IBM 3380 Disk Storage as an indexed sequential data set. Each record in the 
dictionary has a 12-byte key (the word itself) and an 8-byte data area containing a 
parts-of-speech code and control information. Each block contains 50 records; 
LRECL= 20 and BLKSIZE= 1000. Using the formula from Figure 69 on 
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page 220, we find that each track will contain 26 blocks or 1300 records. A total 
of 155 tracks will be required for the dictionary. 


Blocks = 47968/(256+((124+267)/32)(32)+((1000+267) /32)(32)) 
= 47968/1824 = 26 


Records per track = (26 blocks)(50 records per block) = 1300 


Prime data 
tracks = (200000 records / 1300 records per track) + 1 = 155 
required 


Step 2: You will want to anticipate the number of tracks required for cylinder 
overflow areas. The computation is the same as for prime data tracks, but you 
must remember that overflow records are unblocked and a 10-byte link field is. 
added. Remember also that, if you exceed the space allocated for any cylinder 
overflow area, an independent overflow area is required. Those records are not 
placed in another cylinder overflow area. 


Overflow records = Track capacity / Length of overflow records 
per track 


Example: Approximately 5000 overflow records are expected for the data set 
described in step 1. Because 55 overflow records will fit on a track, 91 overflow 
tracks are required. These are 91 overflow tracks for 155 prime data tracks, or 
approximately 1 overflow track for every 2 prime data tracks. Because the 3380 
disk pack has 15 tracks per cylinder, it would probably be best to allocate 5 
tracks per cylinder for overflow. 


Overflow = 47968/(256+((12+267) /32)(32)+((30+267)/32)(32)) 
records = 47968/864 
per track = 55 


Overflow = 5000 records / 55 records per track 
tracks = 9] 
required 


Overflow tracks per cylinder = 5 


Step 3: You will have to set aside space in the prime area for track index entries. 
There will be two entries (normal and overflow) for each track on a cylinder that 
contains prime data records. The data field of each index entry is always 10 bytes 
long. The key length corresponds to the key length for the prime data records. 
How many index entries will fit on a track? 


Index entries = Track capacity / Length of index entries 
per track 


Example: Again assuming a 3380 disk pack and records with 12-byte keys, we 
find that 59 index entries fit on a track. 


Index = 47968/(256+((12+267) /32)(32)+((10+267 ) /32)(32)) 
entries = 47968/832 
per track = 57 
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Step 4: Unused space on the last track of the track index is a function of the 
number of tracks required for track index entries, which in turn depends upon the 
number of tracks per cylinder and the number of track index entries per track. 
You can use any unused space for any prime data records that will fit. 


Unused = (Number of index entries per track) 
space - (2 (Number of tracks per cylinder 
- Number of overflow tracks per cylinder) + 1) 
(Number of bytes per index) 


Note that, for variable-length records, or when a prime data record will not fit on 
the last track of the track index, the last track of the track index is not shared 
with prime data records. In this case, if the remainder of the division 1s less than 
or equal to 2, drop the remainder. In all other cases, round the quotient up to 
the next integer. 


Example: The 3380 disk pack has 15 tracks per cylinder. You can fit 57 track 
index entries into one track. Therefore, you need less than 1 track for each 


cylinder. 


Number of 
trk index 
trks per 
cylinder 


(2 (15 - 5) + 1) / (57 + 2) 
21 / 59 


The space remaining on the track is 47968 - (21 (832)) = 30496 bytes. 


This is enough space for 16 blocks of prime data records. Because the normal 
number of blocks per track is 26, the blocks use 16/26ths of the track, and the 
effective number of track index tracks per cylinder is therefore 1 - 16/26 or 0.385. 


Note that space is required on the last track of the track index for a dummy entry 
to indicate the end of the track index. The dummy entry consists of an 8-byte 
count field, a key field the same size as the key field in the preceding entries, and 
a 10-byte data field. | 


Step 5: Next you have to calculate the number of tracks available on each 
cylinder for prime data records. You cannot include tracks set aside for cylinder 
overflow records. 


Prime data = Tracks per cylinder 


tracks per - Overflow tracks per cylinder 
cylinder - Index tracks per cylinder 


Example: If you set aside 5 cylinder overflow tracks, and you need 0.385ths of a 
track for the track index, 9.615 tracks are available on each cylinder for prime 
data records. 


Prime data tracks = 15 - 5 - (0.385) = 9.615 
per cylinder 


Step 6: The number of cylinders required to allocate prime space is determined 
by the number of prime data tracks required divided by the number of prime data 
tracks available on each cylinder. This area includes space for the prime data 
records, track indexes, and cylinder overflow records. 
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Number of = Prime data tracks needed oo 
cylinders / Prime data tracks per cylinder needed | 
needed eed 


Example: You need 155 tracks for prime data records. You can use 9.615 tracks 
per cylinder. Therefore, you need 17 cylinders for your prime area and cylinder 
overflow areas. 


Number of = (155) / (9.615) = 16.121 (round up to 17) 
cylinders 
required 


Step 7: You will need space for a cylinder index and track indexes. There is a 
cylinder index entry for each track index (for each cylinder allocated for the data 
set). The size of each entry is the same as the size of the track index entries; 
therefore, the number of entries that will fit on a track is the same as the number 
of track index entries. Unused space on a cylinder index track is not shared. 





Number of tracks = (Track indexes + 1) 
required for / (Index entries per track cylinder index) 


Example: You have 17 track indexes (from Step 6). Because 57 index entries fit 
on a track (from Step 3), you need 1 track for your cylinder index. The 
remaining space on the track is unused. 


Number of tracks required = (17 + 1) / 57 = 18 / 57 = 0.316 < 1 
for cylinder index 


Note that, every time a cylinder index crosses a cylinder boundary, ISAM writes 
a dummy index entry that lets ISAM chain the index levels together. The 
addition of dummy entries can increase the number of tracks required for a given 
index level. To determine how many dummy entries will be required, divide the 
total number of tracks required by the number of tracks on a cylinder. If the 
remainder is 0, subtract 1 from the quotient. If the corrected quotient is not 0, 
calculate the number of tracks these dummy entries require. Also consider any 
additional cylinder boundaries crossed by the addition of these tracks and by any 
track indexes starting and stopping within a cylinder. 


Step 8: If you have a data set large enough to require master indexes, you will 
want to calculate the space required according to the number of tracks for master 
indexes (NIM parameter) you specified in the DCB macro or the DD statement. 


If the cylinder index exceeds the NIM specification, an entry is made in the 
master index for each track of the cylinder index. If the master index itself 


_ exceeds the NTM specification, a second-level master index is started. As many 


as three levels of master indexes are created if required. 


The space requirements for the master index are computed in the same way as 
those for the cylinder index. | 


Calculate the number of tracks for master indexes as follows: 


# Tracks for master indexes = 
(# Cylinder index tracks + 1) / Index entries per track 





172 MVS/XA Data Administration Guide 











If the number of cylinder indexes is greater than NTM, calculate the number of 
tracks for a first level master index as follows: 


# Tracks for first level master index = 
(Cylinder track indexes + 1) / Index entries per track 


If the number of first level master indexes is greater than NTM, calculate the 
number of tracks for a second level master index as follows: 


## Tracks for second level master index = 
(First level master index + 1) / Index entries per track 


If the number of second level master indexes is greater than NTM, calculate the 
number of tracks for a third level master index as follows: 


# Tracks for second level master index = 
(Second level master index + 1) / Index entries per track 


Example: ‘Assume that your cylinder index will require 22 tracks. Because large 
keys are used, only 10 entries will fit on a track. Assuming that NTM was 
specified as 2, 3 tracks will be required for a master index, and two levels of 
master index will be created. 


Number of tracks required = (22 + 1) / 10 = 2.3 
for master indexes 


Note that, every time a master index crosses a cylinder boundary, ISAM writes a 
dummy index entry that lets ISAM chain the index levels together. The addition 
of dummy entries can increase the number of tracks required for a given index 
level. To determine how many dummy entries will be required, divide the total 
number of tracks required by the number of tracks on a cylinder. If the 
remainder is 0, subtract 1 from the quotient. If the corrected quotient is not 0, 
calculate the number of tracks these dummy entries require. Also consider any 
additional cylinder boundaries crossed by the addition of these tracks and by any 
track indexes starting and stopping within a cylinder. 


Summary: Indexed Sequential Space Requirement Calculations 


1. How many blocks will fit on a track? 


Blocks = Track capacity / Length of blocks 


2. How many overflow records will fit on a track? 


Overflow records = Track capacity 
/ Length of overflow records per track 


3. How many index entries will fit on a track? 


Index entries = Track capacity / Length of index entries 
per track 


4. How much space is left on the last track of the track index? 


(Number of index entries per track) 

(2 (Number of tracks per cylinder 

Number of overflow tracks per cylinder) + 1) 
(Number of bytes per index) 


Unused 
space 
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How many tracks on each cylinder can you use for prime data records? 


Prime data = Tracks per cylinder 
tracks per - Overflow tracks per cylinder 
cylinder - Index tracks per cylinder 


How many cylinders do you need for the prime data area? 


Number of = Prime data tracks needed 
cylinders / Prime data tracks per cylinder needed 
needed 


How many tracks do you need for the cylinder index? 


Number of tracks 
required for = (Track indexes + 1) 
cylinder index  / Index entries per track 


How many tracks do you need for master indexes? 


Number of tracks | 
required for = (Number of cylinder index tracks + 1) 
master indexes / Index entries per track 


Retrieving and Updating an Indexed Sequential Data Set 


Sequential Retrieval and Update 


To sequentially retrieve and update records in an indexed sequential data set: 


Code DSORG=IS or DSORG= ISU to agree with what you specified when 
you created the data set, and MACRF=GL, MACRF= SK, or 
MACRF= PU in the DCB macro. 


Code a DD statement for retrieving the data set. The data set characteristics 
and options are as defined when the data set was created. 


Open the data set. 
Set the beginning of sequential retrieval (SETL). 


Retrieve records and process as required, marking records for deletion as 
required. 


Return records to the data set. 


Use ESETL to end sequential retrieval as required and reset the starting 
point. 


Close the data set to end all retrieval. 
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Sequential Updates—Indexed Sequential Data Set: Assume that, using the data 
set created in the previous example, you are to retrieve all records whose keys 
begin with 915. Those records with a date (positions 13 through 16) before 
today’s date are to be deleted. The date is in the standard form as returned by 
the system in response to the TIME macro instruction, that 1s, packed decimal 
OO0yyddds. Overflow records can be logically deleted even meee they cannot be 
paysteaty deleted from the data set. 


One way to solve this problem is shown in Figure 60. 


//INDEXDD DD DSNAME=SLATE. DICT, --- 
ISRETR START 0 
DCBD DSORG=IS 
ISRETR CSECT 
USING IHADCB, 3 
LA 3, ISDATA 
OPEN (ISDATA) 
SETL ISDATA, KC ,KEYADDR Set scan limit 
TIME Bn Today's date in register 1 
ST 1, TODAY 
NEXTREC GET ISDATA Locate mode 
CLC 19(10,1), LIMIT 
BNL ENDJOB 
CP 12(4,1); TODAY Compare for old date 
BNL NEXTREC 
MVI 0(1),X'FF' Flag old record for 
| . | deletion _ 
PUTX ISDATA Return delete record 
B NEXTREC 
TODAY DS F 
KEYADDR DC c'915' Key prefix 
DC XL7'0' Key padding 
LIMIT DC c'916' | 
| DC’ XL7'0' 
CHECKERR | 
Test DCBEXCD1 and DCBEXDE2 for error indication 
Error Routines 
ENDJOB CLOSE (ISDATA) 
DCB DDNAME=INDEXDD , DSORG=IS , MACRF=(GL, SK, PU), C 


ISDATA 


SYNAD=CHECKRR 


Figure 60. Sequentially Updating an Indexed Sequential Data Set 
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Direct Retrieval and Update 


By using the basic indexed sequential access method (BISAM) to process an 
indexed sequential data set, you can directly access the records in the data set for: 


® Direct retrieval of a record by its key 
® Direct update of a record 
@ Direct insertion of new records 


Because the operations are direct, there can be no anticipatory buffering. 
However, if ‘S’ is specified on the READ macro, the system provides dynamic 
buffering each time a read request is made. (See Figure 61 on page 178.) 


To ensure that the requested record is in virtual storage before you start 
processing, you must issue a WAIT or CHECK macro. If you issue a WAIT 
macro, you must test the exception code field of the DECB. If you issue a 
CHECK macro, the system tests the exception code field in the DECB. If an 
error analysis routine has not been specified and a CHECK is issued, and an 
error situation exists, the program is abnormally terminated with a system 
completion code of XX’01’ For both WAIT and CHECK, if you want to 
determine whether the record is an overflow record, you should test the eexcepuon 
code field of the DECB. 


After you test the exception code field of the DECB, you need not set it to 0. If 
you have used a READ KU macro and if you plan to use the same DECB again 
to rewrite the updated record using a WRITE K macro, you should not set the 
field to 0. If you do, your record may not be rewritten properly. 


To update existing records, you must use the READ KU and WRITE K 
combination. Because READ KU implies that the record will be rewritten in the 
data set, the system retains the DECB and the buffer used in the READ KU and 
uses them when the record is written. If you decide not to wnite the record, you 
should use the same DECB in another read or write macro or issue a | 
FREEDBUF macro if dynamic buffering was used. If you issue several READ 
KU or WRITE K macros before checking the first one, you may destroy some of 
your updated records unless the records are from different blocks. 


When you are using scan mode with QISAM and you want to issue PUTX, issue 
an ENQ on the data set before processing it and a DEQ after processing 1s 
complete. ENQ must be issued before the SETL macro, and DEQ must be 
issued after the ESETL macro. When you are using BISAM to update the data 
set, do not modify any DCB fields or issue a DEQ until you have issued 


CHECK or WAIT. 
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Sharing a BISAM DCB between Related Tasks: If there is the possibility that 
your task and another task will be simultaneously accessing the same data set, or 
the same task has two or more DCBs opened for the same data set, you should 
use the DCB integrity feature. You specify the DCB integrity feature by coding 
DISP=SHR in your DD statement. In this way you ensure that the DCB fields 
are maintained for your program to process the data set correctly. If you do not 
use DISP=SHR and more than one DCB is open for updating the data set, the 
results are unpredictable. 


If you specify DISP=SHR, you must also issue an ENQ for the data set before 
each input/output request and a DEQ upon completion of the request. All users 
of the data set must use the same qname and rname operands for ENQ. For 
example, the users might use the data set name as the qname operand. (For 
more information about using ENQ and DEQ, see Supervisor Services and Macro 
Instructions.) 


For subtasking, I/O requests should be issued by the task that owns the DCB or 
a task that will remain active as long as the DCB is open. If the task that issued 
the I/O request terminates, the storage used by its data areas (such as IOBs) may 
be freed or queuing switches in the DCB work area may be left set on, causing 
another task issuing an I/O request to the DCB to program check or to enter the 
wait state. For example, if a subtask issues and completes a READ KU I/O 
request, the IOB created by the subtask is attached to the DCB update queue. If 
that subtask terminates, and subpool zero is not shared with the subtask owning 
the DCB, the IOB storage area is freed and the integrity of the ISAM update 
queue is destroyed. A request from another subtask, attempting to use that 
queue, may cause unpredictable abends. As another example, if a WRITE KEY 
NEW is in process when the subtask terminates, 
"WRITE-KEY-NEW-IN-PROCESS " bit is left set on. If another I/O request 
is issued to the DCB, the request is queued but cannot proceed. 


Direct Update with Exclusive Control—Indexed Sequential Data Set: In the 
example shown in Figure 61 on page 178, the previously described data set is to 
be updated directly with transaction records on tape. The input tape records are 
30 characters long, the key is in positions 1 through 10, and the update 
information is in positions 11 through 30. The update information replaces data 
in positions 31 through 50 of the indexed sequential data record. 
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//INDEXDD DD DSNAME=SLATE . DICT, DCB=(DSORG=IS , BUFNO=1,...),--- ae 
//TAPEDD DD ~~ --- | 


ISUPDATE START 0 


NEXTREC GET TPDATA, TPRECORD 
ENQ (RESOURCE , ELEMENT,E, , SYSTEM) 
: READ DECBRW,KU,,'S' ,MF=E Read into dynamically 
ec obtained buffer 
WAIT ECB=DECBRW 
™ DECBRW+24,X'FD' Test for any condition 
BM RDCHECK but overflow 
L 3, DECBRW+16 Pick up pointer to 
* record 
MVC ISUPDATE- ISRECORD Update record 
(L' UPDATE, 3) , UPDATE 
WRITE DECBRW,K,MF=E 
WAIT ECB=DECBRW 
T™ DECBRW+24, X'FD' Any errors? 
BM WRCHECK 
| DEQ (RESOURCE , ELEMENT, , SYSTEM) 
B NEXTREC 
RDCHECK T™ DECBRW+24, X'80' No record found 
BZ ERROR If not, go to error 
* routine 
FREEDBUF DECBRW,K, ISDATA Otherwise, free buffer 
MVC ISKEY, KEY Key placed in ISRECORD 
MVC ISUPDATE , UPDATE Updated information 
* placed in ISRECORD aa 
WRITE DECBRW, KN, ,WKNAREA,'S' ,MF=E Add record to data . 
WAIT ECB=DECBRW 
T™ DECBRW+24, X'FD' Test for errors 
BM ERROR 
DEQ (RESOURCE , ELEMENT, ,SYSTEM) Release exclusive 
* control 
B NEXTREC 
WKNAREA DS 4F BISAM WRITE KN work 
* | field 
ISRECORD DS OCL50 50-byte record from 
* | ISDATA 
DS CL19 DCB First part of 
* ISRECORD 


Figure 61 (Part 1 of 2). Directly Updating an Indexed Sequential Data Set 
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Figure 61 (Part 2 of 2). 
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CL10 Key field of ISRECORD 


Chl Part of ISRECORD 
CL20 Update area of ISRECORD 
ISUPDATE Overlay ISUPDATE with 
OCL30 TPRECORD 30-byte record 
CL10 from TPDATA DCB Key 

for locating 
CL20 ISDATA record update 
CL8' SLATE ' information or new data 
C'DICT' 
DECBRW, KU, ISDATA,'S','S' ,KEY,MF=L 
DDNAME= INDEXDD, DSORG=IS , MACRF=(RUS, WUA), C 


MSHI=INDEX, SMSI=2000 


2000C 


Directly Updating an Indexed Sequential Data Set 


Exclusive control of the data set is requested, because more than one task may be 
referring to the data set at the same time. Notice that, to avoid tying up the data 
set until the update is completed, exclusive control is released after each block 1s 
written. 


Note the use of the FREEDBUF macro instruction in Figure 61. Usually, the 
FREEDBUF macro has two functions: 


e To indicate to the ISAM routines that a record that has been read for update 
will not be written back 


e To free a dynamically obtained buffer 


In Figure 61, because the read operation was unsuccessful, the FREEDBUF 
macro frees only the dynamically obtained buffer. 


The first function of FREEDBUF allows you to read a record for update and 


then decide not to update it without performing a WRITE for update. You can 


use this function even when your READ macro does not specify dynamic 
buffering, provided that you have included S (for dynamic buffering) in the 
MACRF field of your READ DCB. 


You can effect an automatic FREEDBUF merely by reusing the DECB, that 1s, 
by issuing another READ or a WRITE KN to the same DECB. You should 
use this feature whenever possible, because it is more efficient than FREEDBUF. 
For example, in Figure 61, the FREEDBUF macro could be eliminated, because 
the WRITE KN addressed the same DECB as the READ KU. 


For an indexed sequential data set with variable-length records, you may make 
three types of updates by using the basic access technique. You may read a 
record and write it back with no change in its length, simply updating some part 
of the record. You do this with a READ KU followed by a WRITE K, the 
same way you update fixed-length records. 
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Two other methods for updating variable-length records use the WRITE KN AN 
macro and allow you to change the record length. In one method, a record read a - / 
for update (by a READ KU) may be updated in a manner that will change the 

record length and then be written back with its new length by a WRITE KN. In 

the second method, you may replace a record with another record having the 

same key and possibly a different length using the WRITE KN macro. To 

replace a record, it is not necessary to have first read the record. 


In either method, when changing the record length, you must place the new 
length in the DECBLGTH field of the DECB before issuing the WRITE KN 
macro. If you use a WRITE KN macro to update a variable-length record that 
has been marked for deletion, the first bit (no record found) of the exceptional 
condition code field (DECBEXC1) of the DECB is set on. If this condition is 
found, the record must be written using a WRITE KN with nothing specified in 
the DECBLGTH field. 


Do not try to use the DECBLGTH field to determine the length of a record read, 
because DECBLGTH is for use with writing records, not reading them. If you 
are reading fixed-length records, the length of the record read is in DCBLRECL, 
and if you are reading variable-length records, the length is in the record 
descriptor word (RDW). 


Direct Update—Indexed Sequential Data Set with Variable-Length Records: In 

Figure 62, an indexed sequential data set with variable-length records is updated 
directly with transaction records on tape. The transaction records are of variable 
length and each contains a code identifying the type of transaction. Transaction 
code 1 indicates that an existing record is to be replaced by one with the same _ 


Be 


key; 2 indicates that the record is to be updated by appending additional 
information, thus changing the record length; 3 or greater indicates that the 
record is to be updated with no change to its length. For this example, the 
maximum record length of both data sets is 256 bytes. The key is in positions 6 
through 15 of the records in both data sets. The transaction code is in position 5 
of records on the transaction tape. The work area (REPLAREA) size 1s equal to 
the maximum record length plus 16 bytes. 
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/ / INDEXDD 
/ /TAPEDD 


ISUPDVLR 
NEXTREC 


Ps 
ee 


DD 
DD 


START 
GET 
CLI 
BL 
READ 
CHECK 


CLI 
BH 





DSNAME=SLATE . DICT , DCB=(DSORG=IS , BUFNO=1,...),--- 


0 

TPDATA, TRANAREA 

TRANCODE, 2 Determine if replacement or 
other transaction 

REPLACE Branch if replacement 

DECBRW,KU,,'S','S',MF=E Read record for update 

DECBRW , DSORG=IS Check exceptional conditions 

TRANCODE, 2 Determine if change or append 

CHANGE Branch if change 


* CODE TO MOVE RECORD INTO REPLACEA+16 AND APPEND DATA FROM TRANSACTION 


* RECORD 


CHANGE 


MVC 
WRITE 


CHECK 
B 


DECBRW+6( 2) , REPLAREA+16 Move new length from RDW 
into DECBLGTH (DECB+6) 

DECBRW, KN, , REPLAREA, MF=E Rewrite record with 
changed length 

DECBRW , DSORG=IS 

NEXTREC 


* CODE TO CHANGE FIELDS OR UPDATE FIELDS OF THE RECORD 


2 


REPLACE 


% ot 


CHECKERR 


REPLAREA 
TRANAREA 
TRANCODE 
KEY 

TRANDATA 


ISDATA 
TPDATA 


WRITE 
CHECK 
B 

MVC 
WRITE 


CHECK 
B 


DS 
DS 
DS 
DS 
DS 
READ 
DCB 
DCB 


DECBRW,K,MF=E Rewrite record with no 
change of length 

DECBRW , DSORG=IS 

NEXTREC 

DECBRW+6( 2) , TRANAREA Move new length from RDW 
into DECBLGTH (DECB+6) 

DECBRW, KN, , TRANAREA-16,MF=E Write transaction record 
as replacement for record 
with the same key 

DECBRW , DSORG=IS 

NEXTREC 

SYNAD routine 


CL272 

CL4 

CL1 

CL10 

CL241 

DECBRW, KU, ISDATA,'S','S',KEY,MF=L 

DDNAME=INDEXDD, DSORG=IS , MACRF=(RUSC, WUAC ) , SYNAD=CHECKERR 


Figure 62. Directly Updating an Indexed Sequential Data Set with Variable-Length Records 
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Adding Records to an Indexed Sequential Data Set —_ 


Either the queued access technique or the basic access technique may be used to 
add records to an indexed sequential data set. A record to be inserted between 
records already in the data set must be inserted by the basic access method using 
WRITE KN (key new). Records added to the end of a data set, that is, records 
with successively higher keys, may be added to the prime data area or the 
overflow area by the basic access method using WRITE KN, or they may be 
added to the prime data area by the queued access technique using the PUT 
macro. 


Inserting New Records into an Existing Indexed Sequential Data Set 


As you add records to an indexed sequential data set, the system inserts each 
record in its proper sequence according to the record key. The remaining records 
on the track are then moved up one position each. If the last record does not fit 
on the track, it 1s written in the first available location in the overflow area. A 
10-byte link field is added to the record put in the overflow area to connect it 
logically to the correct track. The proper adjustments are made to the track 
index entries. This procedure is illustrated in Figure 63 on page 184. 


Subsequent additions are written either on the prime track or as part of the 
overtlow chain from that track. If the addition belongs after the last prime record 
on a track but before a previous overflow record from that track, it is written in 
the first available location in the overflow area. Its link field contains the address 
of the next record in the chain. Me 


Pi 


For BISAM, if you add a record that has the same key as a record in the data 

set, a “duplicate record” condition is indicated in the exception code. However, if 
you specified the delete option and the record in the data set is marked for 
deletion, the condition is not reported and the new record replaces the existing 
record. (For more information about exception codes, see Data Administration: 
Macro Instruction Reference.) 


Adding New Records to the End of an Indexed Sequential Data Set 


Records added to the end of a data set, that 1s, records with successively higher 
keys, may be added by the basic access method using WRITE KN (key new), or 
by the queued access method using the PUT macro instruction (resume load). In 
either case, records may be added to the pnme data area. 


When you use the WRITE KN macro, the record being added 1s placed in the 
prime data area only if there is room for it on the prime data track containing the 
record with the highest key currently in the data set. If there is not sufficient 
room on that track, the record is placed in the overflow area and linked to that 
prime track even though additional prime data tracks onginally allocated have not 
been filled. 


When you use the PUT macro (resume load), records are added to the pnme 
data area until the space originally allocated is filled. After this allocated prime 
area 1S filled, you can add records to the data set using WRITE KN, in which 
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c case they will be placed in the overflow area. Resume load is discussed in more 
( detail under “Creating an Indexed Sequential Data Set” on page 163. 


In order to add records with successively higher keys using the PUT macro 
(resume load): 


e The key of any record to be added must be higher than the highest key 
currently in the data set. 


e The DD statement must specify DISP= MOD or the EXTEND option 1s 
specified in the OPEN macro. 


e The data set must have been successfully closed when it was created or when 
records were previously added using the PUT macro. 


You may continue to add fixed-length records in this manner until the onginal 
space allocated for prime data is exhausted. 


When you add records to an indexed sequential data set using the PUT macro 
(resume load), new entries are also made in the indexes. During resume load on 
a data set with a partially filled track and/or a partially filled cylinder, the track 
index entry and/or the cylinder index entry is overlaid when the track or cylinder 
is filled. If resume load abnormally terminates after these index entries have been 
overlaid, a subsequent resume load will get a sequence check when adding a key 
that is higher than the highest key at the last successful CLOSE but lower than 
‘le the key in the overlaid index entry. When the SYNAD exit is taken for a 
( sequence check, register 0 contains the address of the highest key of the data set. 


Maintaining an Indexed Sequential Data Set 
An indexed sequential data set must be reorganized occasionally for two reasons: 
e The overflow area will eventually be filled. 
e Additions increase the time required to locate records directly. 


The frequency of reorganization depends on the activity of the data set and on 
your timing and storage requirements. There are two ways you can accomplish 
reorganization: 


e You can reorganize the data set in two passes by writing it sequentially into 
another area of direct access storage or magnetic tape and then re-creating it 
in the original area. 


e You can reorganize the data set in one pass by writing it directly into another 
area of direct access storage. In this case, the area occupied by the original 
data set cannot be used by the reorganized data set. 


The operating system maintains statistics that are pertinent to reorganization. 

The statistics, written on the direct access volume and available in the DCB for 
checking, include the number of cylinder overflow areas, the number of unused 
tracks in the independent overflow area, and the number of references to overflow 
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Figure 63. Adding Records to an Indexed Sequential Data Set 


records other than the first. They appear in the RORG1, RORG2, and RORG3 
fields of the DCB. 


If you indicate when creating or updating the data set that you want to be able to 
flag records for deletion during updating, you can set the delete code (the first 
byte of a fixed-length record or the fifth byte of a variable-length record) to 
X'FEF'. Ifa flagged record is forced off its prime track during a subsequent 
update, it will not be rewritten in the overflow area, as shown in Figure 64 on 
page 185, unless it has the highest key on that cylinder. Similarly, when you 
process sequentially, flagged records are not retrieved for processing. During 
direct processing, flagged records are retrieved the same as any other records, and 
you should check them for the delete code. 
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Note that a WRITE KN (key new) to a data set containing variable-length 
records removes all the deleted records from that prime data track. 


Note that, to use the delete option, RKP must be greater than 0 for fixed-length 
records and greater than 4 for variable-length records. 
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Figure 64. Deleting Records from an Indexed Sequential Data Set 
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Indexed Sequential Buffer and Work Area Requirements | | | ( ; 
The only case in which you will ever have to compute the buffer length (BUFL) 

requirements for your program occurs when you use the BUILD or GETPOOL 

macro to construct the buffer area. If you are creating an indexed sequential data 

set (using the PUT macro), each buffer must be 8 bytes longer than the block 

size to allow for the hardware count field, that is: 


Buffer length = 8 + Block size | 
(8) Data | | 
3 | CBLKSIZE) | 


< Buf fer-——_———______> 





One exception to this formula arises when you are dealing with an unblocked 
format-F record whose key field precedes the data field; its relative key position is 
0 (RKP=0). In that case, the key length must also be added, that is: 


Buffer length = 8 + Key length + Record length 


ays Key Data 
CKEYLEN) CLRECL) 


SS SS a er aS SS 


The buffer requirements for using the queued access technique to read or update 
(using the GET or PUTX macro) an indexed sequential data set are discussed “oN 
below. 7 be a 


For fixed-length unblocked records when both the key and data are to be read 
and for variable-length unblocked records, padding is added so that the data will 
be on a doubleword boundary, that is: 


Buffer length = Key length + Padding + 10 + Block size 


Key . ISAM Link Field Data 
CKEYLEN) Padding €10) CBLKSIZE) 


<— _§ Bu fF fer > 


For fixed-length unblocked records when only data is to be read: 
Buffer length = 16 + LRECL 


Padding| ISAM Link Field — Data — 
(6) (10) CLRECL) 


SS Se DU ere ee 
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For fixed-length blocked records: 
Buffer length = 16 + Block size 


Padding| ISAM Link Field Data 
| (6) (10) CBLKSIZE) 


For variable-length blocked records, padding is 2 if the buffer starts on a fullword 
boundary that is not also a doubleword boundary or 6 if the buffer starts on a 
doubleword boundary, that is: 


“Aw 
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Buffer length = 12 or 16 + Block size 


Padding] ISAM Link Field Data 
C10) C(BLKSIZE) 


Buffer 
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ON 
‘as 
} 


; 
If you are using the input data set with fixed-length, unblocked records as a basis 
for creating a new data set, a work area is required. 

The size of the work area is given by: 


Work area = Key length + Record length 


Key ata 
CLRECL) 


Work Area 


A 
—] 
cr 
Vv 


If you are reading only the data portion of fixed-length unblocked records or 
variable-length records, the work area is the same size as the record, that is: 


Work area = Record length 


ata 
CLRECL) 


Work Area 


© 
re 


A 
Vv 


When you use the basic access technique to update records in an indexed 
sequential data set, the key length field need not be considered in determining 
your buffer requirements. The area for fixed-length records must be: 


Buffer length = 16 + Block size 


Padding; ISAM Link Field Data 
€10) CBLKSIZE) 


Buffer 
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For variable-length records, padding is 2 if the buffer starts on a fullword 
boundary that is not also a doubleword boundary or 6 if a buffer starts on a 
doubleword boundary. Thus, the area must be: 


Buffer length = 12 or 16 + Blocksize 


Padding| ISAM Link Field Data 
(6) C10) CBLKSIZE) — 


$$ $$ Bat fer > 


You can save processing time by adding fixed-length or variable-length records to 
a data set by using the MSWA parameter of the DCB macro to provide a special 
work area for the operating system. The size of the work area (SMSW parameter 
in the DCB) must be large enough to contain a full track of data, the count fields 
of each block, and the work space for inserting the new record. 


The size of the work area needed varies according to the record format and the 
device type. You can calculate it during execution using device-dependent 
information obtained with the DEVTYPE macro and data set information from 
the DSCB obtained with the OBTAIN macro. (The DEVTYPE and OBTAIN 
macros are discussed in System-Data Administration.) 


Note that you can use the DEVTYPE macro only if the index and prime areas 
are on devices of the same type or if the index area is on a device with a larger 
track capacity than that of the device containing the prime area. If you are not 
trying to maintain device independence, you may precalculate the size of the 
work area needed and specify it in the SMSW field of the DCB macro. The 
maximum value for SMSW is 65535. 


For calculating the size of the work area, see the storage device capacities shown 
in Figure 68 on page 219 and the device overhead formulas given in “Estimating 
Space Requirements” on page 218. 


For fixed-length blocked records, SMSW is calculated as follows: 
SMSW = (DS2HIRPR) (BLKSIZE + 8) + LRECL + KEYLEN 


The formula for fixed-length unblocked records is 

SMSW = (DS2HIRPR) (KEYLEN + LRECL + 8) + 2 

The value for DS2HIRPR is in the index (format-2) DSCB. Debugging 
Handbook shows the exact location of this field in the index DSCB. If you don’t 


use the MSWA and SMSW parameters, the control program supplies a work area 
using the formula BLKSIZE + LRECL + KEYLEN. 


For variable-length records, SMSW may be calculated by one of two methods. 
The first method may lead to faster processing, although it may require more 


storage than the second method. 


The first method 1s as follows: 


SMSW = DS2HIRPR (BLKSIZE + 8) + LRECL + KEYLEN + 10 
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The second method 1s as follows: 


SMSW = ( (Trk Cap - Bn + 1) / Block length) (BLKSIZE) 
+ 8 (DS2HIRPR) + LRECL + KEYLEN 
+ 10 + (REM - N - KEYLEN) 


In all the above formulas, the terms BLKSIZE, LRECL, KEYLEN, and SMSW 
are the same as the parameters in the DCB macro (Trk Cap = track capacity). 
REM is the remainder of the division operation in the formula and N is the first 
constant in the block length formulas described in Figure 69 on page 220. 
(REM-N-KEYLEN) is added only if it is positive. 


The second method yields a minimum value for SMSW. Therefore, the first 
method is valid only if its application results in a value higher than the value that 
would be derived from the second method. If neither MSWA nor SMSW is 
specified, the control program supplies the work area for variable-length records, 
using the second method to calculate the size. 


Another technique to increase the speed of processing is to provide space in 
virtual storage for the highest-level index. To specify the address of this area, use 
the MSHI operand of the DCB. When the address of this area 1s specified, you 
must also specify its size, which you can do by using the SMSI operand of the 
DCB. The maximum value for SMSI is 65535. If you do not use this technique, 
the index on the volume must be searched. If the high-level index 1s greater than 
65535 bytes in length, your request for the high-level index in storage is ignored. 


The size of the storage area (SMSI parameter) varies. To allocate that space 
during execution, you can find the size of the high-level index in the 
DCBNCRHI field of the DCB during your DCB exit routine or after the data set 
is open. Use the DCBD macro to gain access to the DCBNCRHI field (see 
Chapter 5, “Specifying a Data Control Block and Initializing Data Sets” on 
page 41). You can also find the size of the high-level index in the DS2NOBYT 
field of the index (format 2) DSCB, but you must use the utility program 
IEHLIST to print the information in the DSCB. You can calculate the size of 
the storage area required for the high-level index by using the formula 


SMSI = (Number of Tracks in High-Level Index) 
(Number of Entries per Track) 
(Key Length + 10) 


The formula for calculating the number of tracks in the high-level index is in 
“Calculating Space Requirements for an Indexed Sequential Data Set” on 
page 169. When a data set is shared and has the DCB integrity feature 

(DISP = SHR), the high-level index in storage is not updated when DCB fields 
are changed. 


Controlling an Indexed Sequential Data Set Device 


An indexed sequential data set is processed sequentially or directly. Direct 
processing is accomplished by the basic access technique. Because you provide 
the key for the record you want read or wnitten, all device control is handled 
automatically by the system. If you are processing the data set sequentially, using 
the queued access technique, the device is automatically positioned at the 
beginning of the data set. 
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In some cases, you may want to process only a section or several separate : 
sections of the data set. You do this by using the SETL macro instruction, 7 ed 
which Girects the system to begin sequential retrieval at the record having a 

specific key. The processing of succeeding records 1s the same as for normal 

sequential processing, except that you must recognize when the last desired record 

has been processed. At this point, issue the ESETL macro to terminate 

sequential processing. You can then begin processing at another point in the 

data set. If you do not specify a SETL macro prior to retrieving the data, the 

system assumes default SETL values. (See the GET and SETL macros in Data 

Administration: Macro Instruction Reference.) 


SETL—Specify Start of Sequential Retrieval 


190 


The SETL macro enables you to retrieve records starting at the beginning of an 
indexed sequential data set or at any point in the data set. Processing that is to 
start at a point other than the beginning can be requested in the form of a record 
key, a key class (key prefix), or an actual address of a prime data record. 


The key class concept is useful because you do not have to know the whole key 
of the first record to be processed. A key class comprises all the keys that begin 
with identical characters. The key class is defined by specifying the desired 
characters of the key class at the address specified in the lower-limit operand of 
the SETL macro and setting the remaining characters to the nght of the key class 
to binary zeros. | 


To use actual addresses, you must keep a record of where the records were | 
written when the data set was created. The device address of the block containing See 
the record just processed by a PUT-move macro instruction is available in the 

8-byte data control block field DCBLPDA. For blocked records, the address is 

the same for each record in the block. 


Normally, when a data set is created with the delete option specified, deleted 
records cannot be retrieved using the QISAM retrieval mode. When the delete 
option is not specified in the DCB, the SETL macro options function as follows: 





SETL B Start at the first record in the data set. 

SETL K Start with the record having the specified key. 

SETL KH Start with the record whose key is equal to or higher than the 
specified key. 

SETL KC Start with the first record having a key that falls into the 


specified key class. 


SETL I Start with the record found at the specified direct access 
address in the prime area of the data set. 


Because the DCBOPTCD field in the DCB can be changed after the data set is 
created (by respecifying the OPTCD in the DCB or DD card), it is possible to 
retrieve deleted records. In this case, SETL functions as noted above. 
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When the delete option is specified in the DCB, the SETL macro options 
function as follows: 


SETLB | Start retrieval at the first undeleted record in the data set. 


SETL K Start retrieval at the record matching the specified key, if that 
record is not deleted. If the record is deleted, an NRF (no 
record found) indication is set in the DCBEXCD field of the 
DCB, and SYNAD is given control. 


SETL KH Start with the first undeleted record whose key is equal to or 
higher than the specified key. 


SETL KC Start with the first undeleted record having a key that falls 
into the specified key class or follows the specified key class. 


SETL I Start with the first undeleted record following the specified 
direct access address. 


With the delete option not specified, QISAM retrieves and handles records 
marked for deletion as nondeleted records. 


Note: Regardless of the SETL or delete option specified, the NRF condition 
will be posted in the DCBEXCD field of the DCB, and SYNAD is given control | 
if the key or key class: 


e Is higher than any key or key class in the data set 
e Does not have a matching key or key class in the data set 

ESETL—End Sequential Retrieval 
The ESETL macro directs the system to stop retrieving records from an indexed 
sequential data set. A new scan limit can then be set, or processing terminated. 
An end-of-data-set indication automatically terminates retrieval. An ESETL 
macro must be executed before another SETL macro (described above) using the 


same DCB 1s executed. 


Note: Ifthe previous SETL macro completed with an error, an ESETL macro 
should be executed before another SETL macro. 
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Chapter 13. Generation Data Groups 





A generation data group is a group of related cataloged data sets. The way these 
data sets are cataloged is what makes them a generation data group. Within a 
generation data group, the generations can have like or unlike DCB attributes 
and data set organizations. If the attributes and organizations of all generations 
in a group are identical, the generations can be retrieved together as a single data 
set. Each data set within a generation data group is called a generation data set. 
Generation data sets are sometimes called generations. 


There are advantages to grouping related data sets. Because the catalog 
management routines can refer to the information in a special index—called a 
generation index—in the catalog: 


e §6All of the data sets in the group can be referred to by a common name. 
e The operating system is able to keep the generations in chronological order. 


¢ Outdated or obsolete generations can be automatically deleted by the 
operating system. 


The management of a generation data group depends upon the fact that 
generation data sets have sequentially ordered names—absolute and relative 
names—that represent their age. The absolute generation name 1s the 
representation used by the catalog management routines in the catalog. Older 
data sets have smaller absolute numbers. The relative name is a signed integer — 
used to refer to the latest (0), the next to the latest (-1), and so forth, generation. 
The relative number can also be used to catalog a new generation (+ 1). 


A generation data group base is created in an integrated catalog facility or VSAM 


catalog before the generation data sets are cataloged. A generation data group 1s 
represented in the integrated catalog facility or VSAM catalog by a generation 


data group base entry. The access method services DEFINE command is used to 


create the generation data group base. See Access Method Services Reference for 
information on how to define and/or catalog generation data sets in an integrated 
catalog facility or VSAM catalog. See Utilities for information on how to define 
and/or catalog generation data sets in an OS CVOL. 
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Absolute Generation and Version Numbers 


An absolute generation and version number is used to identify a specific 
generation of a generation data group. The generation and version numbers are 

in the form GxxxxVyy, where xxxx is an unsigned 4-digit decimal generation 
number (0001 through 9999) and yy is an unsigned 2-digit decimal version 
number (00 through 99). For example: 


® A.B.C.G0001V00 is generation data set 1, version 0, in generation data group 
A.B.C. 


© A.B.C.G0009V01 is generation data set 9, version 1, in generation data group 
A.B.C. 


The number of generations and versions is limited by the number of digits in the 
absolute generation name, that is, 9999 for generations and 100 for versions. 


The generation number is automatically maintained by the system. The number 
of generations kept depends on the size of the generation index. For example, if 
the size of the generation index allows ten entries, the ten latest generations may 
be maintained in the generation data group. 





The version number allows you to perform normal data set operations without 
disrupting the management of the generation data group. For example, if you 


want to update the second generation in a 3-generation group, replace generation eS 
2, version 0, with generation 2, version 1. Only one version is kept for each of 
generation. 


A generation can be cataloged using either absolute or relative numbers. When a 
generation is cataloged, a generation and version number is placed as a low level 
entry in the generation data group. In order to catalog a version number other 
than V00, you must use an absolute generation and version number. 


A new version of a specific generation can be cataloged automatically by 
specifying the old generation number along with a new version number. For 
example, if generation A.B.C.G0005V00 is cataloged and you now create and 
catalog A.B.C.G0005V01, the new entry is cataloged in the location previously 
occupied by A.B.C.G0005V00. This process removes the old entry from the 
catalog but does not scratch the old version. To scratch the old version and 
make its space available for reallocation, a DD card, describing the data set to be 
deleted, with DISP = (OLD,DELETE) should be included at the time the data 
set is to be replaced by the new version. 


Relative Generation Number 


As an alternative to using absolute generation and version numbers when 
cataloging or referring to a generation, you can use a relative generation number. 
To specify a relative number, use the generation data group name followed by a 
negative integer, a positive integer, or a 0, enclosed in parentheses. For example, 
A.B.C(-1). A.B.C(+ 1), or A.B.C(0). 





i94 MVS/XA Data Administration Guide 























The value of the specified integer tells the operating system what generation 
number to assign to a new generation, or it tells the system the location of an 
entry representing a previously cataloged generation. 


When you use a relative generation number to catalog a generation, the operating 
system assigns an absolute generation number and a version number of V00 to 
represent that generation. The absolute generation number assigned depends on 
the number last assigned and the value of the relative generation number that you 
are now specifying. For example if, in a previous job generation, 
A.B.C.G0005V00 was the last generation cataloged, and you specify A.B.C(+ 1), 
the generation now cataloged is assigned the number G0006V00. Though any 
positive relative generation number can be used, a number greater than 1 may 
cause absolute generation numbers to be skipped. For example, if you have a 
single step job, and the generation being cataloged is a + 2, one generation 
number is skipped. However, in a multiple step job, one step may have a + 1 
and a second step a + 2, and no numbers are skipped in this case. 


Note: If you do not specify a volume in the JCL for a new generation data set, 
and the data set is not opened, that data set is not cataloged. 


Programming Considerations for Multiple Step Jobs 





One of the reasons for using generation data groups is to allow the system to 
maintain a given number of related cataloged data sets. If you attempt to delete 
or uncatalog any but the oldest of the data sets of a generation data group in a 
multiple step job, catalog management can lose orientation within the data group. 
This can cause the deletion, uncataloging, or retrieval of the wrong data set when 
referring to a specified generation. The rule is, if you delete a generation data set 
in a multiple step job, do not refer to any older generation in subsequent job 
Steps. 


Also, it is recommended that, in a multiple step job, you catalog or uncatalog 
data sets using JCL instead of IEHPROGM or a user program. Because 
ALLOCATION/UNALLOCATION monitors data sets during job execution 
and is not aware of the functions performed by these programs, data set 
orientation may be lost or conflicting functions may be performed in subsequent 
job steps. 


When you use a relative generation number to refer to a generation that was 
cataloged in a previous job, the relative number has the following meaning: 


¢ A.B.C(0) refers to the latest existing cataloged entry. 

e A.B.C(-1) refers to the next-to-the-latest entry, and so forth. 

When cataloging is requested via JCL, all actual cataloging occurs at step 
termination, but the relative generation number remains the same throughout the 


job. Because this is so: 


e A relative number used in the JCL refers to the same generation throughout 
a job. 
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e A job step that terminates abnormally may be deferred for a later step restart. a 


If the step cataloged a generation data set via JCL, you must change all 
relative generation numbers in the succeeding steps via JCL before 
resubmitting the job. 


For example, if the succeeding steps contained the relative generation numbers: 
e A.B.C(+ 1), that refers to the entry cataloged in the terminated job step, or 
° A.B.C(0), that refers to the next to the latest entry, or 

e A.B.C(-1), that refers to the latest entry, prior to A.B.C(0), 


you must change them as follows before the step can be restarted: A.B.C(0), 
A.B.C(-1), A.B.C(-2), and so forth. 


Generation Data Group Naming for ISO/ANSI/FIPS Version 3 Labels 


In a Version 3 ISO/ANSI/FIPS label (LABEL =(,AL)), the generation number 
and version number are maintained separately from the file identifier. During 
label processing, the generation number and version number are removed from 
the generation data set name. The generation number is placed in the generation 
number field (file label 1 positions 36 through 39), and the version number is 
placed in its position on the same label (position 40 and 41). The file identifier 
portion of a Version 3 HDR1/EOF1/EOVI1 label contains the generation data set 
name without the generation number and version number. 


For Version 3 labels, you must observe the following specifications created by the 
generation data group naming convention. 


@ Data set names whose last 9 characters are of the form .GnnnnVnn (n is 0 
through 9) can only be used to specify GDG data sets. When a name ending 
in .GnnnnVnn is encountered, it is automatically processed as a GDG. The 
generation number Gannn and the version number Vnzn are separated from 
the rest of the data set name and placed in the generation number and 
version number fields. 


e Tape data set names for GDG files are expanded from a maximum of 8 
user-specified characters to 17 user-specified characters. (The tape label file 
identifier field has space for 9 additional user-specified characters because the 
generation number and version number are no longer contained in this field.) 


e A generation number of all zeros is not valid, and will be treated as an error 
during fabel validation. The error appears as a “RANG” error in message 
JEC512I (IECIEUNK) during the label validation installation exit. 


e In an MVS system-created GDG name, the version number will always be 0. 
(MVS will not increase the version number by | for subsequent versions.) 
To obtain a version number other than 0, you must explicitly specify the 
version number (for example, A.B.C.G0004V03) when the data set is created. 
You must also explicitly specify the version number to retrieve a GDG with 
a version number other than 0. | 
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( ¢ Because the generation number and version number are not contained on the 

3 identifier of HDR1, generations of the same GDG will have the same name. 
Therefore, an attempt to place more than one generation of a GDG on the 
same volume will result in an ISO/ANSI/FIPS standards violation in a 
system supporting Version 3, and MVS will enter the validation installation 
exit. 


Creating a New Generation 


To create a new generation data set, you must first allocate space for the 
generation, then catalog the generation. 


Allocating a Generation 


To take full advantage of the facilities of the system, the allocation can be 
patterned after a previously allocated generation in the same group. This is 
accomplished by the specification of DCB attributes for the new generation as 
described below. 


If you are using absolute generation and version numbers, DCB attributes for a 
generation can be supplied directly in the DCB parameter of the DD statement 
defining the generation to be created and cataloged. 


{ If you are using relative generation numbers to catalog generations, DCB 
| attributes can be supplied either: (1) by creating a model DSCB on the volume 
| on which the index resides (the volume containing the catalog) or (2) by referring 
to a cataloged data set for the use of its attributes. Attributes can be supplied 
before you catalog a generation, when you catalog it, or at both times, as follows: 


1. Create a model DSCB on the volume on which your index resides. You can 
provide initial DCB attnbutes when you create your model; however, you 
need not provide any attributes at this tzme. Because only the attributes in 
the data set label are used, the model data set should be allocated with 
SPACE = (TRK,0) to conserve direct access space. Initial or overriding 
attributes can be supplied when you create and catalog a generation.! To 

_ create a model DSCB, include the following DD statement in the job step 
| that builds the index or in any other job step that precedes the step where 
| you create and catalog your generation. 


//name DD DSNAME=datagrpname, DISP=( , KEEP) , SPACE=(TRK,(0)), 
/ UNI T=yyyy , VOLUME=SER=xxxxxx, 
// DCB=(applicable subparameters) 


1 Only one model DSCB is necessary for any number of generations. If you plan to 
use only one model, do not supply DCB attributes when you create the model. 
When you subsequently create and catalog a generation, include necessary DCB 
attributes in the DD statement referring to the generation. In this manner, any 
number of generation data groups can refer to the same model. Note that the 
catalog and model data set label are always located on a direct access volume, even 
for a magnetic tape generation data group. 
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Passing a Generation 


| es 
The DSNAME is the common name by which each generation 1s identified; | 


XXXXXX is the serial number of the volume containing the catalog. If no DCB 
subparameters are wanted initially, you need not code the DCB parameter. 


2. You do not need to create a model DSCB if you can refer to a cataloged data 
set whose attributes are identical to those you desire or to an existing model 
DSCB for which you can supply overriding attributes. To refer to a 
cataloged data set for the use of its attributes, specify DCB = (dsname) on the 
DD statement that creates and catalogs your generation. To refer to an 
existing model, specify DCB = (modeldscbname, your attributes) on the DD 
statement that creates and catalogs your generation. 


A new generation may be passed when created. That generation may then be 
cataloged in a succeeding job step or deleted at the end of the job as in normal 
disposition processing when DISP = (,PASS) is specified on the DD statement. 


However, after a generation has been created with DISP = (NEW,PASS) specified 
on the DD statement, another new generation for that data group must not be 
cataloged until the passed version has been deleted or cataloged. To do so would 
cause the wrong generation to be used when referencing the passed generation 
data set. If that data set was later cataloged, a bad generation would be cataloged 
and a good one lost. 


For example, if A.B.C(+ 1) was created with DISP=(NEW,PASS) specified on ned 
the DD statement, then A.B.C.(+ 2) must not be created with 

DISP = (NEW,CATLG) until A.B.C(+ 1) has been cataloged or deleted. 

By using the proper JCL, the advantages to this support are: 


e JCL will not have to be changed in order to rerun the job. 


e The lowest generation version will not be deleted from the index until a valid 
version 1s cataloged. 


Creating an ISAM Data Set as Part of a Generation Data Group 


To create an indexed-sequential data set as part of a generation data group, you. 
must: (1) create the indexed-sequential data set separately from the generation 
group and (2) use IEHPROGM to put the indexed-sequential data set into the 
generation group. : 


In an integrated catalog facility and VSAM catalogs, use access method services 
commands to catalog the data set. In an OS CVOL, use the RENAME function 
to rename the data set. Then use the CATLG function to catalog the data set. 
For instance, if MASTER is the name of the generation data group, and 

GgggeV wv is the absolute generation name, you would code the following: 


RENAME DSNAME=ISAM, VOL=3380=SCRTCH , NEWNAME=MASTER. GeggeVvv f ~ 
CATLG DSNAME=MASTER.GggggVvv, VOL=3380=SCRTCH i 
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Retrieving a Generation 


A generation may be retrieved through the use of job control language 
procedures. Any operation that can be applied to a nongeneration data set can 
be applied to a generation. For example, a generation can be updated and 
reentered in the catalog, or it can be copied, printed, punched, or used in the 
creation of new generation or nongeneration data sets. 


You can retrieve a generation by using either relative generation numbers or 
absolute generation and version numbers. 


Because two or more jobs can compete for the same resource, generation data 
groups should be updated with care, as follows: 


* No two jobs running concurrently should refer to the same generation data 
group. As a partial safeguard against this situation, use absolute generation 
and version numbers when cataloging or retrieving a generation in a 
multiprogramming environment. If you use relative numbers, a job running 
concurrently may update the generation data group index, perhaps cataloging 
a new generation which you will then retrieve in place of the one you 
wanted. 


e Even when using absolute generation and version numbers, a job running 
concurrently might catalog a new version of a generation or perhaps delete 
the generation you wanted to retrieve. For this reason, some degree of 
control should be maintained over the execution of job steps referring to 
generation data groups. 


Building a Generation Data Group Index 


A generation data group is managed via the information found in a generation 
index. (Note that an alias name cannot be assigned to the highest level of a 
generation index.) The BLDG function of IEHPROGM builds the index. The 
BLDG function also indicates how older or obsolete generations are to be 
handled when the index is full. For example, when the index is full, you may 
want to empty it, scratch existing generations, and begin cataloging a new series 
of generations. 


After the index is built, a generation can be cataloged by its generation data 
group name and either an absolute generation and version number or a relative 


generation number. 


Examples of how to build a generation data group index are found in Utilities, 
under IEHPROGM. 
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Chapter 14. I/O Device Control Macros 


The operating system provides you with several macros for controlling 
input/output devices. Each is, to varying degrees, device dependent. Therefore, 
you must exercise care if you want to achieve device independence. 


When you use the queued access technique, only unit record equipment can be 
controlled directly. When using the basic access technique, limited device 
independence can be achieved between magnetic tape and direct access devices. 
You must check all read or write operations before issuing a device control 
macro. 


CNTRL—Control an I/O Device 





The CNTRL macro performs these device-dependent control functions: 
e Card reader stacker selection (SS) 

e Printer line spacing (SP) 

e Printer carnage control (SK) 

¢ Magnetic tape backspace (BSR) over a specified number of blocks 


e Magnetic tape backspace (BSM) past a tapemark and forward space over the 
tapemark 


e Magnetic tape forward space (FSR) over a specified number of blocks 


e Magnetic tape forward space (FSM) past a tapemark and a backspace over 
the tapemark 


Backspacing moves the tape toward the load point; forward spacing moves the 
tape away from the load point. 


Note that the CNTRL macro cannot be used with an input data set containing 
variable-length records on the card reader. 


If you specify OPTCD= H in the DCB parameter field of the DD statement, you 
can use the CNTRL macro to position DOS tapes that contain embedded DOS 
checkpoint records. The CNTRL macro cannot be used to backspace DOS 
7-track tapes that are written in data convert mode and contain embedded 
checkpoint records. 
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PRTOV—Test for Printer Overflow —_— 
The PRTOV macro tests for channel 9 or 12 of the printer carriage control tape 
or the forms control buffer (FCB). An overflow condition causes either an 
automatic skip to channel | or, if specified, transfer of control to your routine for 
overflow processing. If you specify an overflow exit routine, set DCBIFLGS to 
X‘'00"' before issuing another PRTOV. 


If the data set specified in the DCB is not for a printer, no action is taken. 


SETPRT—Printer Setup 


The SETPRT macro instruction is used to control how information is printed. 
It is used with the 3800 Pnnting Subsystem and with various other universal 
character set (UCS) printers. 


For the IBM 3800 Printing Subsystem, the SETPRT macro instruction is used to 
initially set or dynamically change the printer control information. For additional 
information on how to use the SETPRT macro with the 3800 printer, see JBM 
3800 Printing Subsystem Programmer's Guide. 


For printers that have a universal character set (UCS) buffer and optionally, a 

forms control buffer (FCB), the SETPRT macro instruction is used to specify the 

UCS and/or FCB images to be used. Note that universal character sets for the 

various printers are not compatible. The three formats of FCB images (the FCB - 
image for the 3800 Printing Subsystem, the 4248 format FCB and the 3211 ae 
format FCB) are incompatible. The 3211 format FCB is used by the 3203, 3211, 

4248, 3262 Model 5, and 4245 pnnters. 


IBM-supplied UCS images, UCS image tables, FCB images, and character 
arrangement table modules are included in the SYS1.[MAGELIB at system 
generation time. For 1403, 3203, 3211, 3262 Model 5, 4245, and 4248 printers, 
user-defined character sets can be added to SYSI.IMAGELIB. For a description 
of how images are added to SYS].IMAGELIB and how band names/aliases are 
added to image tables, see Systemm-Data Administration. For the 3800, 
user-defined character arrangement table modules, FCB modules, GRAPHIC 
modules, copy modification modules, and library character sets can be added to 
SYS1LIMAGELIB as described in Utilities. For information on building a 4248 
format FCB (which can also be used for the IBM 3262 Model 5 printer), see 
Utilities. 


The FCB contents can be selected from the system library (or an alternate library 
if you are using a 3800), or defined in your program through the exit list of the 
DCB macro instruction, as discussed under “Exit List (EXLST)” on page 80. 


For a non-3800 printer, the specified UCS or FCB image should be found in one 
of the following: 


e SYSLIMAGELIB 


e Image table (UCS Image only) 





® DCB exit list for an FCB | 
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If the image is not found, the operator is asked to specify an alternate image 
name or cancel the request. 


For a printer that has no carriage control tape, you can use the SETPRT macro 
instruction to select the FCB, to request operator verification of the contents of 
the buffer, or to allow the operator to align the paper in the printer. 


BSP—Backspace a Magnetic Tape or Direct Access Volume 


The BSP macro backspaces one block on the magnetic tape or direct access 
volume being processed. The block can then be reread or rewritten. An attempt 
to rewrite the block destroys the contents of the remainder of the tape or track. 


The direction of movement is toward the load point or beginning of the extent. 
You may not use the BSP macro if the track overflow option was specified or if 
the CNTRL, NOTE, or POINT macro instruction is used. The BSP macro 
should be used only when other device control macros couid not be used for 
backspacing. 


Any attempt to backspace across a file mark will result in a return code of 
X'04' in register 15 and your tape or direct access volume will be positioned 
after the file mark. This means you cannot issue a successful backspace 
command after your EODAD routine is entered unless you first reposition the 
tape or direct access volume into your data set. (CLOSE TYPE=T can position 
you at the end of your data set.) 


You can use the BSP macro to backspace DOS tapes containing embedded DOS 
checkpoint records. If you use this means of backspacing, you must test for and 
bypass the embedded checkpoint records. You cannot use the BSP macro for 
DOS 7-track tapes written in translate mode. 


NOTE —Return the Relative Address of a Block 


The NOTE macro requests the relative address of the block just read or written. 
In a multivolume data set, the address is relative to the beginning of the data set 
on the volume currently being processed. 


For magnetic tape, the address is in the form of a 4-byte relative block address. If 
TYPE= REL 1s specified or defaults, the address provided by the operating 
system is returned in register 1. If TYPE= ABS 1s specified, the physical block 
identifier of a data block on tape is returned in register 0. The relative block 
address or the block identifier can later be used as a search argument for the 
POINT macro. 


For a direct access device, the address is in the form of a 4-byte relative track 
address. The address provided by the operating system is returned in register 1, 


-and the amount of unused space available on the track of the direct access device 


is returned in register 0. 
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POINT—Position to a Block 


The POINT macro causes repositioning of a magnetic tape or direct access 
volume to a specified block. The next read or write operation begins at this 
block. In a multivolume data set, you must ensure that the volume referred to is 
the volume currently being processed. For disk, if a write operation follows the 
POINT macro, all of the track following the write operation is erased, unless the 
data set is opened for UPDAT. POINT is not meant to be used before a 
WRITE macro when a data set is opened for UPDAT. If you specify 
OPTCD = H in the DCB parameter field of the DD statement, you can use the 
POINT macro to position DOS tapes that contain embedded checkpoint records. 
The POINT macro cannot be used to backspace DOS 7-track tapes that are 
written in data convert mode and contain embedded checkpoint records. 


If you specify TYPE= ABS, you can use the physical block identifier as a search 
argument to locate a data block on tape. The identifier may be provided from 
the output of a prior execution of the NOTE macro. 


When using the POINT macro for a direct access device that 1s opened for 
OUTPUT, OUTIN, or INOUT, and the record format is not standard, the 
number of blocks per track may vary slightly. 


SYNCDEV—Controk Data Synchronization 


The SYNCDEV macro controls data synchronization for devices supporting 
buffered write mode. Data still in the buffer may not yet reside on the final 
recording medium. This is referred to as data that is not synchronized. You can 
either | 


¢ Request information regarding synchronization. 
¢ Demand that synchronization occur based on a specified number of data 
blocks that are allowed to be buffered. If zero is specified, synchronization 


will always occur. 


When SYNCDEV completes successfully (return code 0), a value will be returned 
that indicates the number of data blocks remaining in the control unit buffer. 
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Chapter 15. Protecting Data 


Control of confidential data in a data set is provided through password 
protection. You can prevent unauthorized access to payroll data, sales forecast 
data, and all other data sets that require special security attention. An individual 
can use a security-protected data set only after supplying a predefined password. 


Password Protection for Non-VSAM Data Sets 


Password protection as described here applies to non- VSAM data sets only. For 
information on password protection for VSAM data sets, see Access Method 
Services Reference. 


In addition to the usual label protection that prevents opening of a data set 
without the correct data set name, the operating system provides data set security 
options that prevent unauthorized access to confidential data. Two levels of 
protection options are available. You specify these options in the LABEL field 
of a DD statement with the parameter PASSWORD or NOPWREAD. 


e Password protection (specified by the PASSWORD parameter) makes a data 
set unavailable for all types of processing until a correct password is entered 
by the system operator, or for a TSO job by the TSO user. 


e No-password-read protection (specified by the NOPWREAD parameter) 
makes a data set available for input without a password, but requires that the 
password be entered for output or delete operations. 


If an incorrect password is entered twice when a job is being requested by the 
open or EOV routine, the job is terminated by the system. For a SCRATCH or 
RENAME request, a return code 1s given. 


You can request password protection when you create the data set, by using the 
LABEL field of the DD statement in your JCL. The system sets the data set 
security byte either in the standard header label 1 as shown in Magnetic Tape 
Labels and File Structure or in the identifier data set control block (DSCB) as 
shown in Debugging Handbook. After you have requested security protection for 
magnetic tapes, you cannot remove it with JCL unless you re-create the data set 
and scratch the protected data set. 


In addition to requesting password protection in your JCL, you must enter at 


least one record for each protected data set in a data set named PASSWORD, 
which must be created on the system-residence volume. You should also request 
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password protection for the PASSWORD data set itself to prevent both reading 
and writing without knowledge of the password. 


For a data set on a direct access device, you can place the data set under 
protection when you enter its password in the PASSWORD data set. You can 
use the PROTECT macro or the IEHPROGM utility program to add, change, 
or delete an entry in the PASSWORD data set; with either of these methods, the 
system updates the DSCB of the data set to reflect its protected status. This 
provision eliminates the need for you to use JCL whenever you add, change, or 
remove security protection for a data set on a direct access device. System-Data 
Administration describes how to maintain the PASSWORD data set, including 
the PROTECT macro instruction; Utilities describes the IEHPROGM utility 
program. 


RACF Protection for Non-VSAM Data Sets 


Resource Access Control Facility (RACF) protection as described here applies to 
non-VSAM data sets, tape data sets, and tape volumes. For information on 
RACE protection for VSAM data sets, see VSAM Administration Guide. For 
detailed information on RACE protection for data sets, see RACF General 
Information Manual and RACF Security Administrator's Guide. 


RACF is an IBM licensed program that provides access control by identifying 
and verifying users and authorizing access to DASD 


You may define a data set to RACF automatically or explicitly. The automatic 
definition occurs when space 1s allocated for the DASD data set, if the user has 
the automatic data set protection attribute or if PROTECT = YES is coded on 
the DD statement. The explicit definition of a data set to RACE 1s by use of the 
RACF command language. A tape volume is defined to RACE explicitly by use 
of the RACF command language or automatically. All data sets on a tape 
volume are RACEF protected if the volume is RACF protected. 


Five levels of access authority are possible in a RACF-defined data set or tape 
volume. 


ALTER 
You have total control over the data set. If you define the data set or tape 
volume to RACF, you have ALTER access authonty. With ALTER 
authority, you can read and write the data set or tape volume, rename the 
data set, and scratch the data set, and you may authorize other users access 
to the tape volume or data set. 


CONTROL 
For non-VSAM data sets, CONTROL authonity 1s equivalent to UPDATE 
authority. 


UPDATE 
You are authorized to open the data set or tape volume for OUTPUT and 
all other open options. 
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READ 
You are authorized to open the data set or tape volume for INPUT only. 


NONE 
You are not authorized to open the data set or tape volume. 


If a data set is defined to RACF and is password protected, access to the data set 
is authorized only through RACF authorization checking. If a tape volume 1s 
defined to RACE and the data set(s) on the tape volume is password protected, 
access to any of the data sets is authorized only through RACF authorization 
checking of the volume. Data set password protection is bypassed. 


To protect multivolume non-VSAM DASD and tape data sets, you must define 
each volume of the data set to RACF as part of the same volume set. When a 
RACF-protected data set is opened for output and extended to a new volume, 
the new volume is automatically defined to RACF as part of the same volume 
set. When a multivolume physical-sequential data set is opened for output either 
each subsequent volume must be RACF protected as part of the same volume 
set, or the data set must not yet exist on the volume. multivolume tape data set 
is opened for output, either each subsequent volume must be RACF protected as 
part of the same volume set, or the tape volume must not yet be defined to 
RACE. If the first volume opened is not RACF protected, no subsequent 
volume may be RACF protected. If a multivolume data set is opened for input 
(or a nonphysical-sequential data set is opened for output), no such consistency 
check is performed when subsequent volumes are accessed. 


ISO/ANSI/FIPS Version 3 installation exits that execute under RACF will 
receive control during ANSI volume label processing. Control will go to the 
RACHECK preprocessing and postprocessing installation exits. The same 
IECIEPRM exit parameter list passed to ANSI installation exits will be passed 
to the RACF installation exits if the accessibility code is any alphabetic character 
from A through Z. For more information, see Magnetic Tape Labels and File 
Structure. 
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Appendix A. Direct Access Labels 


Only standard label formats are used on direct access volumes. Volume, data set, 
and optional user labels are used (see Figure 65). In the case of direct access 
volumes, the data set label is the data set control block (DSCB). 












IPL Records 


Volume Label 
Additional Labels 


fe a eee 


| DCSB | 


Cylinder 


Cylinder O 
Tracks 






Track O 





VTOC 






All Remaining 
Tracks of Volume 


Unused Storage 


Area for Data Sets 





Figure 65. Direct Access Labeling 


Volume-Label Group 


The volume-label group immediately follows the first two initial program loading 
(IPL) records on track 0 of cylinder 0 of the volume. It consists of the initial 
volume label at record 3 plus a maximum of seven additional volume labels. The 
initial volume label identifies a volume and its owner, and is used to verify that 
the correct volume is mounted. It can also be used to prevent use of the volume 
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by unauthorized programs. The additional labels can be processed by an a 
installation routine that is incorporated into the system. Kee! sb 


The format of the direct access volume label group is shown in Figure 66. 


CAs many as Seven Additional Volume Labels) 
80-—Byte Physical Record 


Volume Label Identifier CVOL)D 
Volume Label Number (]) 


Field 1 


Volume Serial Number 


Volume Security 


VTOC Pointer 


Reserved (Blank) 


Owner Identification 


Blank 





Figure 66. Initial Volume Label 


Initial Volume Label Format 
The 80-byte initial volume label is preceded by a 4-byte key containing VOLI. 
Volume Label Identifier (VOL): Field 1 identifies a volume label. 


Volume Label Number (1): Field 2 identifies the relative position of the volume 
label in a volume label group. It must be written as X’F 1’. 


The operating system identifies an initial volume label when, in reading the initial 
record, it finds that the first 4 characters of the record are VOL 1. 


Volume Serial Number: Field 3 contains a unique identification code assigned 
when the volume enters the system. You can place the code on the external 
surface of the volume for visual identification. The code is normally numeric 
(000001 through 999999), but may be any 1 to 6 alphameric or national (#, $, @) 
characters, or a hyphen (X“60’). If this field is less than 6 characters, it 1s padded 
on the night with blanks. 


Volume Security: Field 4 is reserved for use by installations that want to provide 
security for volumes. Make this field a X’CO’ unless you have your own security 
processing routines. 
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VTOC Pointer: Field 5 of direct access volume label 1 contains the address of 
the VITOC in the form of CCHHR. 


Reserved: Field 6 1s reserved for possible future use. Leave it blank. 


Owner Name and Address Code: Field 7 contains a unique identification of the 
owner of the volume. 


All the bytes in Field 8 are left blank. 


Data Set Control Block (DSCB) 


The system automatically constructs a DSCB when space is requested for a data 
set on a direct access volume. Each data set on a direct access volume has one or 
more DSCBs to describe its characteristics. The DSCB appears in the VTOC 
and, in addition to space allocation and other control information, contains 
operating system data, device-dependent information, and data set characteristics. 
There are seven kinds of DSCBs, each with a different purpose and a different 
format number. For an explanation of Format-1 through Format-6 DSCBs, see 
System—Data Administration. Format 0 DSCBs are used to indicate empty space 
in the VTOC. 


User Label Groups 


User header and trailer label groups can be included with data sets of physically 
sequential or direct organization. The labels in each group have the format _ 
shown in Figure 67. 


80-Byte Physical Record (Maximum of 8) 


Label Identifier CUHL if Header, UTL if Trailer) 
Label Number (1 — 8) 


User—Specified 


Figure 67. User Header and Trailer Labels 


Each group can include as many as eight labels, but the space required for both 
groups must not be more than | track on a direct access device. The current 
minimum track size allows a maximum of eight labels, including both header and 
trailer labels. Consequently, a program becomes device dependent (among direct 
access devices) when it creates more than eight labels. 
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If user labels are specified in the DD statement (LABEL=SUL), an additional vo 
track is normally allocated when the data set is created. No additional track is 
allocated when specific tracks are requested (SPACE = (ABSTR....)), or when 7 
tracks allocated to another data set are requested (SUBALLOC=....). In either 

case, labels are written on the first track that is allocated. 


User Header Label Group: The operating system writes these labels as directed 
by the processing program recording the data set. The first 4 characters of the 
user header label must be UHLI,..., UHL8; you can specify the remaining 76 
characters. When the data set is read, the operating system makes the user header 
labels available to the problem program for processing. 


User Trailer Label Group: These labels are recorded (and processed) as explained 
in the preceding text for user header labels, except that the first 4 characters must 
be UTLI.,...,UTL8. 


User Header and Trailer Label Format 


212 


Label Identifier: Field 1 indicates the kind of user header label. UHL indicates a 
user header label; UTL indicates a user trailer label. 


Label Number: Field 2 identifies the relative position (1 to 8) of the label within 
the user label group. 


User-Specified: Field 3 (76 bytes). 
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Appendix B. Control Characters 


As an optional feature, each logical record, in any record format, may include a 
control character. This control character is recognized and processed if a data set 
is being written to a printer or punch. 


For format-F and format-U records, this character is the first byte of the logical 
record. 


For format-V records, it must be the fifth byte of the logical record, ummediately 
following the record descriptor word. 


Two options are available. If either option is specified in the DCB, the character 
must appear in every record and other line spacing or stacker selection options 
also specified in the DCB are ignored. | 





Machine Code 


You can specify in the DCB that the machine code control character has been 
placed in each logical record. If the record is to be written, the appropriate byte 
must contain the command code bit configuration specifying both the wnte and 
the desired carnage or stacker select operation. 


The machine code control characters for a printer are: 


Print—Then Act Immediately 
Act Action without Printing 
X01’ Print only (no space) 

X09’ Space 1 line X‘0OB’ 

X11’ Space 2 lines X13’ 

x’19 Space 3 lines X’1B’ 

X89’ Skip to channel 1 X’8B’ 

x'9)’ Skip to channel 2 X93" 

X99’ Skip to channel 3 X’9B’ 
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Print—Then Act Immediately 


Act Action without Printing 
X’Al’ Skip to channel 4 x’ A3’ 

x’AD Skip to channel 5 x’AB’ 

X’BI’ Skip to channel 6 x’ B3’ 

X’BY’ Skip to channel 7 X’BB’ 

X’CI’ Skip to channel 8 X’C3’ 

X’C9’ Skip to channel 9 X’CB’ 

Xx’DI’ Skip to channel 10 X’D3’ 

x’D9 Skip to channel 11 X’DB’ 

X’EV Skip to channel 12 X’E3’ 


The machine code control characters for a card read punch device are as follows: 


Control Code Action 

X’O1’ Select stacker 1 
x41’ Select stacker 2 
X’5A’ Change from line 


mode to page mode 
X’81’ Select stacker 3 


'The 3800 Model 3 all-point-addressable mode uses this code to change from 
comparability to page mode. 


Other command codes for specific devices are contained in publications 
describing the control units and devices. 
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es 
ae 


Pe ! 


Extended American National Standards Institute Code 





In place of machine code, you can specify control characters defined by the 
American National Standards Institute (ANSI). Whenever IBM publications 
refer to ANSI control characters, they are coded as follows: 


Code Action before Printing a Line 
b Space one line (blank code) 
0 Space two lines 


- Space three lines 


Suppress space 


Skip to channel | 
2 Skip to channel 2 
3 Skip to channel 3 
4 Skip to channel 4 

( 5 Skip to channel 5 

6 Skip to channel 6 
7 Skip to channel 7 
8 Skip to channel 8 
9 Skip to channel 9 
A Skip to channel 10 
B Skip to channel 11 
C Skip to channel 12 
Code Action after Punching a Card 
V Select punch pocket 1 
W Select punch pocket 2 
| xX’ 5A" Change from line to page mode 


| 'The 3800 Model 3 all-point-addressable mode uses this code 
( : These control characters include those defined by ANSI FORTRAN. If any 


other character is specified, it is interpreted as ‘b’ or a V, depending on whether it 
is for a printer or a punch; no error indication is returned. 
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Appendix C. Allocating Space on Direct Access Volumes 








When direct access storage space is required for a data set, you can specify the 
amount of space needed, the device type, and, optionally, the volume. The 
operating system selects the device and allocates the space accordingly. 


When the data set is to be stored on a direct access volume, you must supply, in 
the DD statement, control information designating the amount of space to be 
allocated and how it 1s to be allocated. 


The amount of space required can be specified in blocks, tracks, or cylinders. If 
you want to maintain device independence, specify your space requirements in 
blocks. If your request is in tracks or cylinders, you must be aware of such 
device considerations as cylinder and track capacity. 


Cylinder allocation allows faster input/output of sequential data sets than does 
track or block allocation unless your device supports Define Extent or Locate 
Record. 


Allocation by Blocks: When the amount of space required is expressed in blocks, 
you must specify the number and average length of the blocks within the data set, 
as in this example: 


// DD SPACE=(300,(5000,100)), 


300 = average block length in bytes 
5000 = primary quantity (number of blocks) 
100 = secondary quantity, to be allocated if the primary 


quantity is not enough (in blocks) 


From this information, the operating system estimates and allocates the number 
of tracks required. Space is always in complete tracks. You may also request 
that the space allocated for a specific number of blocks begin and end on cylinder 
boundaries. 


You must be certain that both the quantity and the increment are large enough 
to contain the largest block to be written. Otherwise, all the space requested is 
allocated but erased as the system tries to find a space large enough for the 
record. 


Allocation by Tracks or Cylinders: The amount of space required can be 
expressed in tracks or cylinders, as in these examples: 


// DD SPACE=(TRK,(100,5)), 
// DD SPACE=(CYL,(3,1)), . 
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Allocation by Absolute Address: If the data set contains location-dependent 
information i in the form of an absolute track address (MBBCCHHR), space 
should be requested about the number of tracks and the beginning address, as in 
this example: 


// ODD SPACE=(ABSTR, (500, 15)), UNIT=3380, 


where 500 tracks are required, beginning at relative track 15, which 1s cylinder 1, 
track 0. 


Allocation of Mass Storage System (MSS) Virtual Volumes: When the data set 
is to be stored on an MSS virtual volume, a volume group (MSVGP) parameter 
may be specified instead of using the SPACE parameter on the DD card. Before 
the MSVGP parameter can be used, the volume group must be identified to MSS 
by the utility program IDCAMS. 

Allocation of | MSS Saual volume space should be in multiples of cylinders, with 
secondary allocation a multiple of the primary to ensure maximum space usage 
and minimum fragmentation. 

Additional Space Allocation Options: The DD statement provides you with 


much flexibility in specifying space requirements. The options are described in 
detail in J CL. | 


Estimating Space Requirements 


To determine how much space your data set requires, you must consider these 
variables for the device type: 


e Track capacity 

: Tracks per cylinder 

e Cylinders per volume 
e Data length (block size) 

¢ Key length | 

e Device overhead 


Figure 68 on page 219 lists the physical characteristics of several direct access 
storage devices. | 
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( Maximum Number 





Volume’ Block size Tracks per of Total 
Device Type per Track! Cylinder Cylinders? Capacity!” 
2305-2 Disk 14660 8 96 11258880 
3330/3333° 
(Model 1) Disk 13030 19 404 100018280 
3330/3333 
(Model 11) Disk 13030 19 808 200036560 
3340/33444 Disk 8368 12 696 
(70 megabytes) 69889536 
348 
(35 megabytes) 34944768 
3350 Disk 19069 30 555 317498850 
3375 Disk 327605 12 959 409868928 
3380 Disk 32760° 15 885 630243900 
| 3380 
| (Models 
| AD4 and BD4) Disk 327605 1S 885 630243900 
3380 
(Models 
AF4 and BE4) Disk 327609 15 1770 1260487800 


| Capacity indicated in bytes (when RO 1s used by the IBM programming system). 

2 Excluding alternate cylinders. 

3. The Mass Storage System (MSS) virtual volumes assume the characteristics of the 3330/3333, Model 1. 
4 The 3344 is functionally equivalent to the 3340 Model 70. 


| ° The largest record that can be written on a track is 35616 bytes for the 3375 and 47476 bytes for all 
| 3380 models. However, for these devices, the largest block size supported by the standard access 
| methods is 32760 bytes. 


Figure 68. Direct Access Storage Device Capacities 


The term device overhead refers to the space required on each track for hardware 
data, that is, address markers, count areas, gaps between records, record 0, and so 
forth. Device overhead varies with each device and depends also on whether the 
blocks are written with keys. To compute the actual space required for each 
block, including device overhead, you can use the formulas in Figure 69 on 

page 220. Note that any fraction of a byte must be ignored in any operation of 
the calculation. For example, if the formula gives 15.644 bytes, you must allocate 


( 15 bytes. 
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Track 
Device Capacity 
2305-2 14858? 
3330/3333 13165 
(Model 1 or 
11) 
3340/3344 85352 
3350 19254 
3375 36000 
3380 47968 
(all models) 
( 
3380 Models 47968 
AD4 and BD4 
3380 Models 47968 


AF4 and BE4 


Figure 69. Direct Access Device Overhead Formulas 


Note: You may choose to use the TRKCALC macro to perform track capacity -_ 
calculations. See System— Data Administration for further information on ce 
TRKCALC. - 
Bytes Required by Each Data Block! 
Blocks with Keys Blocks without Keys 
289+ KL+ DL 198+ DL 
191+ KL+DL 135+ DL 
242+ KL+ DL 167+ DL 
267+ KL+ DL 185+ DL 
224+ ((KL+ 191)/32)(32)+ 224+((DL+ 191)/32)(32) 
((DL + 191)/32)(32) 
256 + ((KL + 267)/32) 256+ ((DL + 267)/32)(32) 
(32) +((DL + 267)/32)(32) 
256+ ((KL + 267)/32) 256+ ((DL + 267)/32)(32) ‘ 
(32) + ((DL + 267)/32)(32) aed 
256 + ((KL + 267)/32) 256+ ((DL + 267)/32)(32) 
(32)+((DL + 267)/32)(32) 
Legend: 
DL 1s data length. 
KL is key length. 
Notes: 
1 Use modulo-32 arithmetic when calculating key length and data length terms 
in your equations. Compute these terms first, then round up to the nearest 
increment of 32 bytes before completing the equation. 
2 - This value is different from the maximum block size per track because the 
formula for the last block on the track includes an overhead for this device. 
3. The.Mass Storage System (MSS) virtual volumes assumes the characteristics 
of the 3330/3333, Model 1. 
The formulas can be combined in the following way: 
If you intend to specify your space requirements in tracks (TRK) or cylinders f 
(CYL), your estimate should be made as shown above. If you request absolute aed 





tracks (ABSTR), remember that you cannot allocate track 0, cylinder 0. The 
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amount of space required for the VTOC will reduce the space available on the 
rest of the volume. 





If you specify your space requirements in average block length, the system 
performs the computations for you. 


Because a sequential data set and a direct data set are created in the same way, 
the estimate and specification of space requirements are identical. If you use the 
WRITE SZ macro, your secondary allocation for a direct data set should be at 
least 2 tracks. Space allocation for a partitioned data set requires that you also 
consider the space used for the directory. Similarly, allocation for an indexed 
sequential data set requires that you consider the space needed for the prime area, 
index areas, and overflow areas. 
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Appendix D. ISO/ANSI/FIPS Record Control Word and Segment 
Control Word 


Translation of ISO/ANSI/FIPS Record Control Word 


The ISO/ANSI/FIPS record control word (RCW) is expressed in ISCII/ASCII 
characters and is 4 bytes long (see Figure 70). Note that the RCW is different 
from the code in the IBM record descriptor word (RDW). The RDW, expressed 
in binary, is the internal data management equivalent of the ISO/ANSI/FIPS 
RCW. 


D/DB RDW | ISO/ANS!I RCW 





Output Translation 








Binary Value Length in 
|e [isctvascn 
Numeric 


LL Character Character 


Data Data 






input Translation 


Figure 70. Translation of ISO/ANSI/FIPS Record Control Word to D/DB Record Descriptor Word 
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Translation of ISO/ANSI/FIPS Segment Control Word 


The ISO/ANSI/FIPS segment control word (SCW) is expressed in ISCII/ASCII 
characters and is 5 bytes in length. (See Figure 71.) Note that the SCW is 
different from the code in the IBM segment descriptor word (SDW). The SDW 


is the internal data management equivalent of the ISO/ANSI/FIPS SCW. Only 4 


bytes are used by data management, but the user buffer area must accommodate 
an extra byte to allow for translation from the ISO/ANSI/FIPS SCW. The SDW 
is expressed in binary. 


DS/DBS SDW ISO/ANSi SCW 


Reserved 





Output Translation | Spanning Indicator 













Binary Value 


Length in 
| ISCII/ASCII 
| Segment Position Numeric 
Indicator Characters 





Input Translation 





' C values for SDW (2 low order 
bits) 
00 = only segment of record 
= first segment of record 
11 = mtermediate segment of record 
= last segment of record 


2 S$ values for SCW (ASCII characters) 


only segment of record 

first segment of record 
intermediate segment of record 
last segment of record 


Hoi ue dl 


0 
1 
2 
3 


Figure 71. Translation of ISO/ANSI/FIPS Segment Control Word to DS/DBS Segment Descriptor Word 


224 MVS/XA Data Administration Guide 











Re ee re ee a 





Glossary of Terms and Abbreviations 


The following terms are defined as they are used in this 
book. If you do not find the term you are looking for, 
see the index or the JBM Vocabulary for Data 
Processing, Telecommunications, and Office Systems, 
GC20-1699. 

A. ANSI control code (value of RECFM) 

ABE. abnormal end (value of EROPT) 

ABEND. abnormal end (macro instruction) 

ABSTR. absolute track (value of SPACE) 

ACC. accept erroneous block (value of EROPT) 


AFF. affinity (channel separation parameter of DD 
statement or unit affinity value of UNIT) 


AL. American National Standard Labels 
ANSI. American National Standards Institute 


ASCII. American National Standard Code for 
Information Interchange 


AUL. American National Standard user labels (value 
of LABEL) 


B. blocked records (value of RECFM) 

BCDIC. binary coded decimal interchange code 
BDAM. basic direct access method 

BDW. block descriptor word 

BFALN. buffer alignment (operand of DCB) 
BFTEK. buffer technique (operand of DCB) 
BISAM. basic indexed sequential access method 
BLDL. build list (macro instruction) 

ELKSIZE. blocksize (operand of DCB) 


BPAM. basic partitioned access method 








BPI. bytes per inch 
BSAM. basic sequential access method 


BSM. backspace past tapemark and forward space 
over tapemark (operand of CNTRL) 


BSP. backspace one block (macro instruction) 


BSR. backspace over a specified number of blocks 
(records) (operand of CNTRL) 


BUFCB. buffer pool control block (operand of DCB) 
BUFL. buffer length (operand of DCB) 
BUFNO. buffer number (operand of DCB) 


BUFOFF. buffer offset (length ef ASCIT block prefix 
by which the buffer is offset; operand of DCB) 


CCW. channel command word 


CONTIG. contiguous space allocation (value of 
SPACE) 


CNTRL. control (macro instruction) 
CSW. channel status word 


CYLOFL. number of tracks for cylinder overflow 
records (operand of DCB) 


D. format-D GSCII/ASCII variable-length) records 
(value of RECFM) 


DA. direct access (value of DEVD or DSORG) 


DAU. direct access unmovable data set (value of 
DSORG) 


DB. ISCII/ASCH variable-length, blocked records 
(value of RECFM) 


DBS. ISCII/ASCII variable-length, blocked spanned 
records (value of RECFM) 


DCB. data control block (control block name or macro 
instruction or parameter on DD statement) 
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DCBD. data control block dummy section (macro 
instruction) 


DD. data definition(statement) 

DEB. data extent block 

DECB. data event control block 

DEN. magnetic tape density (operand of DCB) 
DEVD. device-dependent (operand of DCB) 


DISP. data set disposition (parameter of DD 
statement) 


DS. ISCIL/ASCII variable-length, spanned records 
(value of RECFM) 


DSCB. data set control block 
DSORG. data set organization (operand of DCB) 


EBCDIC. extended binary-coded decimal interchange 
code 


EKODAD. end-of-data set exit routine address (operand 
of DCB) 


EOF. end-of-file 
EOV. end-of-volume 
EROPT. error options (operand of DCB) 


ESETL. end sequential retrieval (QISAM macro 
instruction) 


EXCP. execute channel program (macro instruction) 
EXLST. exit list (operand of DCB) 

F. fixed-length records (value of RECFM) 

FB. fixed-length, blocked records (value of RECFM) 


FBS. fixed-length, blocked, standard records (value of 
RECFM) 


FBT. fixed-length, blocked records with track overflow 
option (value of RECFM) ~~ 


FCB. forms control buffer 
FEOV. force end-of-volume (macro instruction) 
FIPS. Federal Information Processing Standard 


FS. fixed-length, standard records (value of RECFM) 
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FSM. forward space past tapemark and backspace 
over tapemark (operand of CNTRL) 


FSR. forward space over a specified number of blocks 
(records) (operand of CNTRL) 


GCR. group coded recording(tape recording mode) 
GL. GET macro, locate mode (value of MACRF) 
GM. GET macro, move mode (value of MACRF) 


H. DOS tapes with embedded checkpoint records 
(parameter of OPTCD) 


HA. home address 

ICF catalog. integrated catalog facility catalog 
INOUT. input then output (operand of OPEN) 
I/O. input/output 

IOB. input/output block 

IPL. initial program load 

IRG. interrecord gap 

IS. indexed sequential (value of DSORG) 
ISAM. indexed sequential access method 


ISCII. International Standard Code for Information 
Interchange 


ISO. International Organization for Standardization 
ISU. indexed sequential unmovable (value of DSORG) 
JCL. job control language | 
JFCB. job file Sans block 


JFCBE. job file control block extension for 3800 
printer 


K. 1024 

KEYLEN. key length (operand of DCB) 

LPA. link pack area 

LPALIB. link pack area library 

LRECL. logical record length (operand of DCB) 
LRI. peal record aicetaes 


M. machine control code (value of RECFM) 





MACRF. macro instruction form (operand of DCB) 
MOD. modify data set (value of DISP) 


MSHI. main storage for highest-level index (operand 
of DCB) 


MSS. Mass Storage System 

MSVC. Mass Storage Volume Control 

MSWA. main storage for work area (operand of DCB) 
NCP. number of channel programs (operand of DCB) 


NOPWREAD. no password required to read a data set 
(value of LABEL) 


NRZI. nonreturn-to-zero-inverted (tape recording 
mode) 


NSL. nonstandard label (value of LABEL) 


NTM. number of tracks in cylinder index for each 
entry in lowest level of master index (operand of DCB) 


OPTCD. optional services code (operand of DCB) 
OS CVOL. operating system control volume 
OS/VS. operating system/virtual storage 

OUTIN. output then input (operand of OPEN) 
PCI. program-controlled interruption 

PDAB. parallel data access block 

PDS. partitioned data set 

PE. phase encoding (tape recording mode) 

PL. PUT macro, locate mode (value of MACRF) 
PM. PUT macro, move mode (value of MACRF) 
PQ. partitioned organization (value of DSORG) 


POU. partitioned organization unmovable (value of 
DSORG) | 


PRTSP. printer line spacing (operand of DCB) 
PS. physical sequential (value of DSORG) 


PSU. physical sequential unmovable (value of 
DSORG) 


QISAM. queued indexed sequential access method 


QSAM. queued sequential access method 








RACF. Resource Access Control Facility 
RDBACK. read backward (operand of OPEN) 
RDW. record descriptor word 

RECFM. record format (operand of DCB) 

RKP. relative key position (operand of DCB) 
RLSE. release unused space (DD statement) 
RPS. rotational position sensing 

S. standard format records (value of RECFM) 
SDW. segment descriptor word 

SER. volume serial number (value of VOLUME) 


SETL. set lower limit of sequential retrieval (QISAM 
macro instruction) 


SF. sequential forward (operand of READ or WRITE) 
SK. skip to a printer channel (operand of CNTRL) 
SKP. skip erroneous block (value of EROPT) 

SL. IBM standard labels (value of LABEL) 


SMSI. size of main-storage area for highest-level index 
(operand of DCB) 


SMSW. size of main-storage work area (operand of 


DCB) 

SP. space lines on a printer (operand of CNTRL) 

SS. select stacker on card reader (operand of CNTRL) 
SUL. IBM standard and user labels (value of LABEL) 
SVC. supervisor call 

SVCLIB. supervisor call library 


SYNAD. synchronous error routine address (operand 
of DCB) 


SYSIN. system input stream 
SYSOUT. system output stream 


T. track overflow option (value of RECFM); 
user-totaling(value of OPTCD) 


TIOT. task I/O table 


TRC. table reference character 
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TRTCH. track recording iechnlaue (operand of DCB) 
U. undefined length records (value of RECFM) 

UCS. universal character set 

UHL. user header label 

UTL. user trailer label 


V. format-V (variable-length) records (value of 
RECFM) 
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VB. variable-length, blocked records (value of 
RECFM) 


VBS. variable-length, blocked, spanned records (value 
of RECFM) 


VS. variable-length, spanned records 
VSAM catalog. virtual storage access method catalog 
VTOC. volume table of contents 


XLRI. extended logical record interface 








Index 


abbreviations 225-228 
ABE error option 78 
abend exit 97-102 
abend installation exit 103 
abnormal termination 
abend installation exit 103 
during open, close, or EOV processing 50 
ESTAE exit 157 
STAE exit 157 
STAI exit 157 
ISO/ANSI/FIPS Version 3 tapes 50 
absolute actual address 
defined 7 
absolute generation name 193 
ACC error option 78 
access method services 
DEFINE command 10 
program use of 11 
access methods 
basic 61-73 
defined 2 
queued 2, 35-68 
selecting 35, 36 
access techniques 
basic 2, 61-73 
queued 2, 35-68 
acronyms 225-228 
actual device addressing 
BDAM 36 
actual track address 
(MBBCCHHR) 
description 7 
use with direct data sets 153 
use with feedback option 153 
address, direct access storage device 
absolute actual 
description 7 


direct 149 
indirect 150 
relative 


description 7 
in directories 132-135 
use with direct data sets 152 
addressing, types of (BDAM) 36 
alias names in a directory 
effect of changing directory entry 141 
specifying 133 
alignment of buffers 120 
allocation, space 
See space allocation 
American National Standard Code for Information 
Interchange 
See ASCII block prefix 
American National Standard Institute 








See ANSI control characters 
American National Standard labels 9 
ANSI control characters 
described 215 
device type considerations 29 
used with chained scheduling 116 
anticipatory buffering 
omitted with basic access technique 61] 
with queued access method 65 
ASCII format 
restriction for 7-track tape 29 
translating data from 116 
associated data sets 
restriction with chained scheduling 115 
ATLAS macro 73 
automatic blocking/deblocking with queued access 
methods 65 
automatic cataloging of data sets 5 
automatic error options 
See EROPT 
automatic volume switching 57 
FEOV macro 57, 65, 114 
auxiliary storage | 
See data set storage, direct access storage, magnetic 
tape volumes 


backspacing 
BSP macro 203 
CNTRL macro 201 
basic access method 
See also BDAM, BISAM, BPAM, and BSAM 
overlapped I/O 61 
basic access technique 
See also BDAM, BISAM, BPAM, and BSAM 
blocking 61 
deblocking 61 
definition of 61-73 
using BDW_ 18 


“BCDIC translation to EBCDIC 30 


BDAM data set 
See also basic access method 
See also basic access technique 
access technique 149 
adding records 154-156 
CHECK macro 64 
creating 150 
dynamic buffering 124, 149 
exclusive control for updating 153 
extended search option 153 
feedback option 153 
organization 149 
processing 149-156 
READ macro _ 62, 63 
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record format 154 
selecting an access method 35, 36 
sharing data set 70, 72 


spanned variable-length records 19-23 


SYNAD routine 78 
updating records 154-156 
user labels 81, 156 
WAIT macro 64 
when sharing a data set 70, 72 
WRITE macro 63 
BDW (block descriptor word) 18 
BFTEK operand (DCB macro) 
BFTEK=A_ 20, 123 
BFTEK=R spanned records 62 
BISAM data set 
See also indexed sequential data set 
dynamic buffering 124 
retrieving 174-180 
sharing a DCB 71 
updating 174-181 
when sharing a data set 70, 71 
BLDL macro 
build list format 139 
coding example 143 
description 139 
set 142 
BLKSIZE operand (DCB macro) 
description 43 
effect of data check on 43 
for card reader and punch 30 
for writing a short block 119 
including block prefix 23 
requirement for direct data set 149 
specifying 59, 217 
when ignored 106, 135 
block count exit routine 94-95 
block descriptor word (BDW) 18 
block prefix (SCIL/ASCID records 
buffer alignment 120 
block prefix (ISO/ANSI) records 
with format-D records 24 
with format-F records 17 
block prefix (ISO/ANSI/FIPS) records 
with format-D records 23 
with format-U records 27 
block prefix records 
with format-F records 13 
block size limitation 
ISO/ANSI spanned records 24 
ISO/ANSI Version 3 tapes 43 
block, data 13 
blocking 
automatic 65 
defined 13 
records 
BSAM_ 38 
QISAM 38 
QSAM 39 
with basic access technique 61] 
with fixed-length records 14-17 
with spanned records 19 
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with undefined-length records 27 
with variable-length records 17-19 


boundary alignment 


buffer 120 
data control block 46 


BPAM data set 


concatenation 113, 146 
creating 136-137 
defined 2, 131-133 
EODAD routine 76 
processing 131-146 
restriction with 
chained scheduling 144 
DCB abend exit routine 97 
fixed-length records, standard format 15 
retrieving member 143 
space allocation for 135, 136 
updating member 144 
when sharing a data set 70, 71 


BSAM data set 


as SYSIN/SYSOUT data sets 105 
creating 109,110 

creating a BDAM data set 150 
EODAD routine 76 

extending 113 

how EODAD routine is entered 76 
overlap of ['O 61, 62, 115 
retrieving 110 

to update the directory 141 
updating 112 

user labels 83 

user totaling 86-87 

when sharing a data set 70, 71 
writing a short block 119 


BSP macro 


description 203 
restriction in EODAD routine 76 


BUFCB operand (DCB macro) 120 
buffer 


See also FREEBUF, FREEDBUF, GETBUF, 
RELSE 
acquisition and control 119 
alignment 120 
automatic for ISAM 
direct 119, 124 
dynamic 119, 124 
control 123-130 
for basic access technique 119, 121 
length 
BUFL operand 120, 186 
number (BUFNO operand of DCB macro) 115, 
120 
number (BUFNO operand) 121 
releasing 129 
segment 119, 123 
truncating 129 


buffer pool 


See also BUILD, GETPOOL, FREEPOOL 
automatic construction 120, 121 
building 120 




















coding examples 122 
creating 121 
description 120 
explicit 120 
freeing 122-123 
getting a buffer from 129 
returning a buffer to 129 
returning a dynamic buffer to 129 
static 120 
buffering 
anticipatory 
for queued access method 65 
- omitted for basic access technique 61 
direct control of 124 
dynamic 119 
exchange 128 
look-ahead 65 
problem program controlled 
BDAM 36 
BPAM 37 
simple 119, 124-128 
BUFL operand (DCB macro) 
for card punch 31 
for constructing a buffer pool 120 
for printer 32 
ISAM 186 
BUFNO operand (DCB macro) 
affecting chained scheduling 115 
affecting performance 115 
constructing a buffer pool 121 
when constructing a buffer pool 120 
when ignored 106 
BUFOFF operand (DCB macro) 
with format-DB records 116 
with QSAM or BSAM 16 © 
with variable-length records 23-24 
BUILD macro | 
description 120 
with ISAM data set 186 
BUILDRCD macro 
description 121 
restriction 21 
usage 20, 21 


CAMLST macro 10 
capacity for direct access 
cylinder 6, 221 
record 6, 150 
track 221 
card punch 
record format 30, 31 
card reader | 
record format with 30-31 
relationship with CNTRL macro 201 
restriction with CNTRL macro 201 
carriage control characters 





defined 31, 213 

specification of in RECFM field 29 
CATALOG macro 10 
catalog, system 

entering a data set name 10 

OS CVOL 9,10 
cataloging data sets 

automatic 5 

defined 1 

for a generation data group 193-195 
CCW (channel command word) 

creation by OPEN 47 

PCI flag in 115 

use in simple buffering 124 
chained scheduling 


BSAM_ 116 
DASD 116 
description 109, 115 
QSAM_ 116 


restriction with 
calculating record length 117 
CNTRL macro 115 


DOS checkpoint records, embedded on 


tape 115 
format-D records 23 
partitioned data set 144 
SKP option 78 _ 
spooled data sets 115 
3525 Card Punch 115 


shai an address in the data control block 46, 47 


changing the data control block 47 
channel command word (CCW) 

See CCW 
channel programs 

execute (EXCP) 3, 35 | 

number of (NCP) 62, 106, 115 
CHECK macro 

description 64 

to enter EODAD routine 76 

to update a partitioned data set 144 

to update a sequential data set 112 

use with BDAM_ 157 

use with SYNAD routine 61, 78 

using WAIT instead - | 

‘See WAIT macro °' 

when sharing a data set 70, 157 

with basic access technique 6] 
check routine, examining DECB 64 
checkpoint/restart 

check of JFCBFLAG 94 

restriction for LPALIB 94 
CHKPT macro 

use in end-of-volume exit routine 94 
CLOSE macro 

description 52-55 

for multiple data sets 54 

for parallel input processing 67-68 

in EODAD routine 76 

restriction with SYNAD 52, 78 

temporary close option 52-55 

TYPE=T 52-55 
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volume positioning 47, 52, 56 
with partitioned data set 141-142 
with STOW macro 141 
closing a data set 52-55. 
CNTRL macro 
device dependence 201 
restrictions 
with BSP macro 203 
with chained scheduling 115 
with DOS checkpoint records 201 
concatenation 
data sets 
BPAM 37 
partitioned 146 
sequential 113 
unlike 113 
defined 113, 146 
control buffer 
See forms control buffer 
control characters 
See also CNTRL, PRTOV 
ANSI 23, 29, 116 
carriage 3], 213, 215 
code 213, 214 
explained 31] 


format-D 23 
format-F 15 
format-U 27 
format-V 19 


ISO/ANSI/FIPS 15 
machine 29, 116, 213, 214 
specifying 29, 213 
with fixed-length records 15 
with undefined-length records 27 
with variable-length records 19 
control section, dummy (DSECT) 46 
count area | 
count data format 8 
count key data format 6 
in device overhead 219 
ISAM index entry format 162 
cross reference table with direct data sets 150 
CSECT statement 
with DCBD macro 46 
cylinder 
allocation by 217 
capacity 6, 218 
index 
calculating space requirements for 166 
definition 160, 162 
overflow 
calculating space for 166, 170 
defined 163 
specifying size via CYLOFL parameter 167 
CYLOFL operand (DCB macro) 
allocating ISAM data set 167 
creating ISAM data set 163 
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D-format records 
See format-D records | 
data access techniques 
See access techniques 
data checks 
effecton BLKSIZE 43 
data control block 
See DCB 
data definition name (ddname) field (DD statement) 
data definition statement 
See DD statement 
data event control block 
See DECB 
data management 
introduction 1, 71, 72 
data mode processing 
relationship with buffers 123 
data set 
characteristics 1 
description 43 
disposition (DISP) operand 
description 45 
overridden by OPEN macro 56 
identification 3 
label (LABEL) field of DD statement 45 
like characteristics 113, 146 
name 3 
name (DSNAME) field 45 
organization 
DSORG operand (DCB macro) 44 
RECFM (record format) 13-28, 31 
routing through the input/output stream 105-107 
security 205, 206 
space allocation 
a direct data set 150 
estimation 218-22] 
indexed sequential data sets 166-174 
partitioned data sets 135, 136 
specifying 217-218 
space allocation on direct access volumes 136 
storage 
direct access 5 
magnetic tape 8 
SYSIN 105-107 
SYSOUT 105-107 
unlike characteristics 113, 146 
unmovable 
resulting from use of MMBBCCHHR_ 8 
data set control block 
See DSCB 
DCB (data control block) 
abend exit 
description 97-99 
when available 75 
where specified 75 
attributes of, determining 41 
changing 47 


45 


ao 


j 


ee” 














changing an address in 46, 47 
creation by DCB macro 4, 4] 
description 41-42 
dummy control section 46 
exit 
description 88 
when available 75 
when used by SYSIN/SYSOUT 105 
where specified 75 | 
fields 43 — 
modifying 41, 45 
operand of DD statement 45 
primary sources of information 41 
sequence of completion 42 
use 4 
when sharing a data set 69 


DCB abend exit 97-99 
DCB macro 
QISAM 38 


DCBBLKSI field in DCB 32, 119 
DCBD macro 46 

restriction 46 

use 46 
DCBLPDA field of DCB 190 
DCBNCRHI field of DCB 189 
DCBPRECL field of DCB 19 
DCBSYNAD field of DCB 47 
DD statement 

fields 43 

relationship to DCB 41 

relationship to JFCB 41 

use of 4 
DD statement fields 45 
DDNAME operand © 

See data definition name field 
deblocking, automatic 65 
DECB (data event control block) 

description 65 

use of 112 
defer nonstandard input trailer label exit 95 
DEFINE command 10 
defining an FCB image 95, 96 
delete option 


_ restriction when updating a sequential data set 112 


restriction with RKP 185 
use with SETL 191 
deleting 
indexed sequential data set records 184 
member name using STOW macro 141 
DEN (tape density) 29-30 
density, tape 29-30 
DEQ macro 70, 71, 177 
descriptor word 
See block descriptor word, record descriptor word, 
segment descriptor 
determinate errors 49 | 
DEVD operand (DCB macro) 
device-class independence considerations 59 
restriction with SYSOUT data sets 106 
specifying 29 
with BDAM 150 











with SYSOUT data sets 106 


device control for sequential data sets 201-204 


device independence 58-59 
device type 
considerations for data format 
sequential organization 28, 33 
device-dependent macros 201 
DEVTYPE macro 188 
direct access device 
characteristics 44 
direct access storage devices 
See DASD 
direct access volume 
access mechanism 6 
description 5 
device characte SiGe 
labels 6 
RECFM (record format) 28, 31 
record format 28-29, 33 
record format (RECFM) 5 
track addressing 7 
track format 6 
track overflow 7 
track, defined: 6 
write validity check 44 
direct addressing 149 
direct data set 
See BDAM data set 
direct organization | 
See BDAM data set 
directory 
See BPAM data set © 
directory, partitioned data set 
creation 37 
DISP operand 
action of 57 | 
description 45, 56° 
for extending sequential data set 113 
for indexed sequential data set 183 
for partitioned data set 141 
for tape 42, 85 


6-44 


when DISP=SHR for sharing data sets 70, 177 


when passing a generation 198 
when updating the directory 141 
DOS (disk operating system) 
embedded checkpoint records 
restriction with BSP 203 
restriction with chained scheduling 
restriction with CNTRL 201 
restriction with POINT 204 
DSCB (data set control block) 
contents of 211 
data set label 209-212 
data set security byte 205 
described 6, 21] 
index (format-2) DS2HTRPR field of 
DSECT statement 46 
DSNAME operand 
DD statement 45, 140, 142 
DSORG operand (DCB macro) 
CLOSE TYPE=T 54 


115 


189 


Index 
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described 44 

direct data set 150 

indexed sequential data set 163 

partitioned data set 136, 140, 141 

sequential data set 109, 110 
dummy control section 

for DCB 46 
dummy data set 

restriction with parallel input processing 67 
dummy records 

with direct data set 151, 154 
dynamic buffering | 

buffer control 121, 149 

for direct data set 149 

for ISAM data set 164, 176 

specifying 121 


EBCDIC (extended binary coded decimal interchange 
code) 
for magnetic tape volumes 9 
record format dependencies 13-31 
translation to and from ASCII 116 
translation to and from ISCII/ASCII 1, 9, 63, 65, 
66 
embedded index area 166, 167 
end-of-block 
See EOB | 
end-of-data indicator 55 
end-of-data routine 
See EODAD routine 
end-of-sequential retrieval 
See ESETL 
end-of-volume 
exit routine 94 
forcing 57, 58 
processing 55-58 | 
routines, relationship with DCB abend exit 97, 99 
when EODAD routine entered 76, 77 
ENQ macro | 
when sharing a data set 70, 71 
EOB (end-of-block) 
fixed-length records 16 
EODAD (end-of-data) routine 
changing address of in DCB 46-47 
specifications 76-77 
with basic access technique 61 
with BSP macro 203 
with concatenated data sets 114 
with GET macro 65 | 
with queued access technique 65 
EROPT (automatic error options) operand (DCB 
macro) 78 
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error | 
analysis routine (SYNAD) 77-79 
determinate 49 
handling 72 
indeterminate 49 
_ options, automatic 78 
-uncorrectable 77 
error routine 
See SYNAD routine 
ESETL (end-of-sequential retrieval) macro 
description 191 
in EODAD routine 76, 77 
when sharing a data set 71 
ESTAE exit, abnormal termination 157 
exceptional condition code 
See condition, exceptional 
exchange buffering 128 
exclusive control 
updating direct data sets 153 
when sharing direct data sets 71 
EXCP (execute channel program) 3 
EXCP macro 35 
execute channel program (EXCP) 3 
exit list 79-81 
list 81 
exit routine 
block count 94-95 
conventions 82 — 
DCB (data control block) 88 
DCB abend 97-102 
defer nonstandard input trailer label 95 
end-of-data 76-77 
end-of-volume 94 
FCB image 95 
identified by DCB 75 
JFCBE 93 
list 79 | 
QSAM parallel input 93 
register contents on entry 82 
standard user label 82-86 
synchronous error (SYNAD) 77-79 
user totaling 86 
EXLST operand (DCB macro) 77, 79 
EXTEND operand (OPEN macro) 
device independence 58 
extending sequential data set 113 
indexed sequential data set 183 
QISAM use 51 
specifying 42 
use with SYSIN/SYSOUT 51 


extended binary coded decimal interchange code 


See EBCDIC 


extended logical record interface (XLRI) 27 


extended search option 
for direct data sets 153 








ao 


Ma 








F-format records 
See format-F records 
FCB (forms control buffer) 
image 
exit 95 
identification in JFCBE 93 
relationship with SETPRT 202 
FCB images 
formats of 202 
feedback 
option 153 
with BDAM READ macro _ 63 
with BDAM WRITE macro 64 
FEOV macro 
description 57, 58 
ignored for SYSIN/SYSOUT data sets 58 
restriction with spanned records 20, 57 
restriction with trailer label exit 85 
to enter EODAD routine 76 
file access exit 5] 
file mark, restriction 203 
FIND macro 
description 139-140 
in EODAD routine 76, 77 
updating a partitioned data set 144 
when sharing a data set 71 
fixed-length records 
description 14-17 
with parallel input processing 66 
force end-of-volume 
See FEOV macro 
format-D records, restriction with chained 
scheduling 23 
format-F records 
description 13-17 
ISO/ANSI tapes 17 
ISO/ANSI/FIPS tapes 15 
standard format 14-15 
with card reader and punch 30-31 
with parallel input processing 66 
format-S records 
extended logical record interface 27 
segment descriptor word 24 
format-U records 
calculating record length 117 
description 27 
restriction for ISO/ANSI tapes 28 
with card reader and punch 30 
with parallel input processing 66 
format-V records 
block descriptor word 18 
description 18-23 
record descriptor word 19 
segment control codes 21 











segment descriptor word 2] 
spanned 19 

with card punch 30-31 

with parallel input processing 66 


forms control buffer 


See FCB 


FREE operand 55 
FREEBUF macro 


description 129 
example 178 

for ISAM 176 

to control buffers 119 


FREEDBUF macro 


description 129 
when sharing data sets 157 


FREEPOOL macro 


when issued for card punch data set 31 
when issued for printer data set 32 
when used 122 


full-track-index write option 164 


generation data group 


absolute generation name 193 
building an index 199 
creating anew 197, 198 
defined 5, 193 
entering in the catalog 193, 194, 195 
naming conventions 

Version 3 labels 196 
relative generation name 193 
retrieving 199 


generation data set 193 
generation index 193 
generation number field 


Version 3 labels 196 


generation numbers 


relative 193, 197 


GET macro 


description 65 
in EODAD routine 76 


restriction with spanned records to enter EODAD 


routine 76 
updating a sequential data set 112 
when sharing a data set 70 
with format-U records 28 
with parallel input processing 66, 67 


GETBUF macro 


description 129 
to control buffers 119 


GETPOOL macro 


with ISAM data set 186 


glossary 225-228 
grouping related control blocks 61 


Index 
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[H| 


header label 
user 82, 86, 212 


| 


IDCAMS program 218 
IEBCOPY program 145, 146 
IECOENTE macro 
nonspecific tape volume mount exit 
IECOEVSE 
IEHATLAS program 73 
IEHLIST program 167, 189 
IEHMOVE program 133, 134 
JIEHPROGM program 198 
IHADCB DSECT 
label 46 
independent overflow area 
description 163 
specifying 169 
indeterminate errors 49 
index 
area 
calculating space for 166-167 
creation of 159 
cylinder 
calculating space for 166 
overflow area 163 
master 
calculating space for 166 
using 160 
space allocation for 39 
track 
calculating space for 167 
track 160 
indexed sequential data set 
adding records 182-183 


89 


areas 159-162, 163, 166-174, 186-189 
allocating space for 166-174, 186-189 


index 161-162 

overflow 163 

prime 160 
buffer requirements 186 
creation 163-166 
deleting records 184 
device control 189-191 
full-track-index write option 164 
inserting new records 182 
new records at the end 182 
retrieving 174-177 
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SYNAD routine 79 
updating 174-181 
indirect addressing 150 


INOUT operand (OPEN macro) 42, 51, 204 


INPUT operand (OPEN macro) 42, 51 
input/output devices 
magnetic tape 29 
with sequential data sets 
card reader and punch 30, 31 
direct access 33 
magnetic tape 30 
printer 32 
input/output errors 
recovering from 73 
installation exit 
ISO/ANSI/FIPS Version 3 tapes 50 
with RACF 207 
interrecord gaps (IRGs) 13 


IOB, relationship with SYNAD routine for BDAM 


IRG (interrecord gap) 13 
ISAM 


See indexed sequential data set, BISAM, QISAM 


ISCIT/ASCII block prefix 

restriction 13, 15, 23 

with format-D records 23 

with format-F records 13-16 

with format-U records 27 
ISCIL/ASCII format 

translating data from 1, 13, 65 

translating data to 1, 13, 63, 66 
ISCIT/ASCII tape 

buffer alignment 120 
ISO/ANSI tape 

Version 3 

block size limitation 43 

ISO/ANSI/FIPS control characters 

with format-D records 23 


with format-F ISO/ANSI/FIPS tape records 


ISO/ANSI/FIPS tape 
fixed-length records 15 
undefined-length records 27 
variable-length records 23 


~ 


JES Gob entry subsystem) 105-107 

JFCB (job file control block) 41, 49 

JFCBE (job file control block extension) 
exit 93 | 

JFCBFLAG 94 

job file control block 41, 49 

job file control block extension (JFCBE) 
exit 93 











key 
class 190 
for direct access devices 7 
for indexed sequential data sets 159-162 
RKP (relative key position) for indexed sequential 
data set 163, 185, 186 
use of when adding records to indexed sequential 
data set 182 
use of when maintaining an indexed sequential data 
set 184 
use of when retrieving records from an indexed 
sequential data set 176-181 
KEYLEN operand (DCB macro) 
description 44 
for direct access device 33 
for direct data set 150 
specifying 59 
KN 
See WRITE with KN 
KU 
See READ with KU 


label exits 82-86 
LABEL parameter in DD statement 
description 45 
specifying password protection 205 
specifying standard labels 84 
label symmetry conflict 
ISO/ANSI Version 3 tapes 51 
label validation exit 50 
labels 
direct access 209 
data set control block 209-212 
format 209 
user label groups 21] 
volume label group 209-211 
LEAVE option 
for close processing 52, 54 
for concatenated data sets 114 
for end-of-volume processing 56, 57 
for forced end-of-volume processing 57 
length checking 14 
link field 186, 187 
link pack area 


library 
restriction for checkpoint 94 
load mode 
BDAM 
when sharing data sets 157 
QISAM 38 


in SYNAD routine 79 
when sharing a DCB 72 








load module 
attribute assignment 
fields 41 
loading an indexed sequential data set 164 
locate mode 
defined for buffering 123 
example with simple buffering 126, 127, 128 
relationship with buffers 123 
to process records that exceed 32760 bytes 21 
to update a member with QSAM_ 144 
with GET macro 
creating a sequential data set, coding 
example 111 
simple buffering 109, 111, 125-128 
with parallel input processing 
example 68 
simple buffering 124-128 
logical record interface (LRI) 20 
look-ahead buffering 65 
LPALIB 
restriction for checkpoint 94 
LRECL operand (DCB macro) 
coding in K units 27 
described 44 
device dependence 59 
to process records that exceed 32760 bytes 21 
with BDAM_ 150 
with BSAM_ 119 
with ISAM 
buffer requirements 188 
data set creation 163 
with PUT macro 66 
with SYSOUT data set 105 
LRI (logical record interface) 
spanned records 20 


machine control characters 29, 116 
MACRF operand (DCB macro) 

device independence 59 

dynamic buffering 179 

for BDAM 150 

relationship with WAIT macro 64 

to update a member using QSAM_ 144 

when sharing a data set 70, 72 
magnetic tape volumes 


defined 8 
density 29-30 
labels 
American National Standard 9 
none 5 
nonstandard 5 
standard 5 
user 82-86 
organization 8 
positioning 


during close processing 52-55 
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during end-of-volume processing 56, 57 
RECFM (record format) 8-28, 29, 31 
serial number 9 
tapemarks 9 
mass storage system 146 
master catalog 10 
master index 162 
MBBCCHHR 
See actual track address 
mode 
See also MACRF operand 
load (QISAM) 38 
resume load mode 38 
scan (QISAM) 38 
modes, processing 
See data mode, locate mode, move mode, substitute 
mode 
modifying the data control block 41, 45 
move mode processing 
relationship with buffers 123 
use instead of exchange buffering 128 
with GET macro 
creating a sequential data set 109 
simple buffering 109, 125-128 
with parallel input processing 66 
with PUT macro 
creating a sequential data set 109 
simple buffering 109, 125-128 
MSS (Mass Storage System) 
staging 146 
MSVGP parameter on JCL statement 218 
MSWA operand (DCB macro) 188 
multiple data sets 
closing 48 
opening 48 
processing for QISAM. 120 
multitasking mode, sharing data séts 48, 50, 72 
multivolume data set 
with NOTE macro 203 





names 
data set 3 
generation data group 5, 193, 194, 195 
NCP operand (DCB macro) 62, 106, 115 
nonsequential processing of sequential data 38 
nonspecific tape volume mount exit 88-90 
general register rules 90 
IECOENTE macro parameter list 89 
return codes 88 
how specified 89 
nonstandard tape labels 5, 8 
note list 134 
NOTE macro 
ABS parameter 203 
description 203 
restriction with 203 
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BSP macro 203 a 
multivolume data sets 203 Ww / 
updating a sequential data set 112 
use with partitioned data set updating 144 
NTM operand (DCB macro) 162 
null segment 22 


[o} 


offset reading 62 
OMR 
See optical mark read 
OPEN macro 
considerations for 49, 50 
description 51-53 
for parallel input processing 67 
for simultaneous opening of multiple data sets 48 
for updating a sequential data set 112 
functions 42, 5]-53 
used for more than one data set 48 
volume positioning for EOV 56 
OPEN/EOV volume security/verification exit 90-93 
general register rules 93 
IECOEVSE 91 
return codes 9] 
how specified 91 we 
opening a data set 47-50 : 
OPTCD operand (DCB macro) Sat 
device dependence 116 
request user totaling (OPTCD=T) 86 
with BDAM 151 
with ISAM 164 
with ISCII/ASCIT tapes (OPTCD=Q) _ 65, 66 
OPTCD=H 
embedded checkpoints, DOS tapes 
positioning DOS tapes 201 
MSS staging 146 | 
OPTCD=M (master index) 162 
OPTCD =T (user totaling) 86 
OS CVOL 39, 10 
OUTIN operand (QPEN macro) 42, 51, 204 
OUTINX operand (OPEN macro) 42, 51, 58 
output mode, defined 124 
OUTPUT operand (OPEN macro) 42, 51, 204 
when using POINT macro 204 
output stream 105-107 
overflow 
area 159, 163 
chain 182 
cylinder 
See cylinder overflow 
independent area 163 
PRTOV macro 202 
records 163 
track > 
description 7 ‘+ y 
restriction on BSP macro 203 ba 
restriction with parallel input processing 67 




















restriction with RPS feature 117 processing mode 123 


overflow, track used to create a sequential data set, coding 
restrictions example 110 
ISAM 38 with format-U records 28 
overlap of input/output | with indexed sequential data set 182-183 
performance improvement 115 with simple buffering 125-128 
with partitioned data sets 144 PUTX macro 
with queued access method 65 description 66 
with sequential data sets 112 device independence 59 


UPDAT mode 127 
updating a sequential data set 112 


when sharing a data set 70 
| P| with format-U records 28 
: with simple buffering 125-128 


padded record 24 
end-of-block condition 16° 
paging environment, related control block group 61 | Q| 
parallel data access block (PDAB) 67, 93 
parallel input processing 66-68, 93 


parameter list QISAM data set 
contents of 97 See also ISAM 
use of by DCB abend exit routine 97-99 EODAD routine 76 
partitioned data set scan mode 176 
See also BPAM data set sharing 70, 72 
general description 37 SYNAD routine 77-79 
PASSWORD data set 205 using common buffer pool 120 
password protection 205, 206 QSAM (queued sequential access method) 
PC (card punch) record format 30-31 See also queued access technique 
PCI flag 115 creating a BDAM data set 150 
PDAB (parallel data access block) 67, 93 parallel input processing 66-68 
PDS performance improvement 115 
See BPAM data set restriction with spanned records 20 
performance improvement 115 spanned variable-length records 20 
POINT macro SYSIN/SYSOUT data sets 105 
description 204 to update a directory 141 
in EODAD routine 76 to update a member 144 
relationship to user labels 83 
BSAM 38 user totaling 86-87 
restriction with when sharing a data set 70, 71 
BSP macro 203 with card punch 31 
multivolume data sets 204 © with printer 32 
updating a partitioned data set 144 queued access method 
updating a sequential data set 112 defined 65 
prefix, block | queued access technique 
See block prefix buffer control 119, 123 
prefix,key 190 |. defined 35 | 
prime data area introduced 2 
description 159, 160 processing modes 
space allocation for 166, 168 See data mode processing 
printer 
overflow (PRTOV macro) 202 
record format with 32 
program, describing the processing 2-102 | R| 
PRTOV macro 


description 202 
device dependent 59 RACF 


when macro will not function 202 installation exit 207 
PUT macro protection 206, 207 


description 66 RD (card reader) 30-31 
locate mode 123-128 RDBACK operand (OPEN macro) 


Index 
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label exit routine 85 
opening magnetic tape volume 42 
restriction for variable-length records 51 
restriction with SYSIN/SYSOUT data sets 51 
RDW (record descriptor word) | 
data mode exception for spanned records 19 
extended logical record interface 27 | 
variable-length records format-D 23, 24, 25 
when replaced by segment descriptor word 21 
read backward | 
SB operand of READ macro 62 
READ macro _ 
description 62 
device independence 59 
in SYNAD routine 78 
restriction in EODAD routine 76 
to enter EODAD routine 76 
to update existing records 176 
updating a partitioned data set 144 
updating a sequential data set 112 
when sharing a data set 70, 157 
with basic access method 62 
with format-U records 28 
with KU (key, update), in coding example 178 
RECFM (record format) 
fixed-length 17 
fixed-length for ISO/ANSI 17 
spanned variable-length 19 
undefined-length 27 
variable-length 17-24 
RECFM operand (DCB macro) 
description 44 
for sequential data sets 28 
selecting 14. 
with card punch 30-3] 
with card reader 30-31 
with control character 29 
with direct access storage device 33 
with magnetic tape 29-30 
with printer 32 
with sequential organization 28-29 
record blocking 
See blocking 
record descriptor word 
See RDW 
record format 
See RECFM 
record format (RECFM) 
fixed-length 14 
fixed-length for ISO/ANSI/FIPS = 15 
fixed-length standard 14 
record length (LRECL) operand (DCB macro) 44, 59 
relative addressing 
BDAM 36, 
relative block address 
with direct data set 152 
with feedback option 153 
relative generation name 193-197 
relative key position (RKP) operand (DCB 
macro) 163,185, 186 
relative track address 
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defined 8 | | oo 
with direct access 152 | | ee 
with feedback option 153 
releasing data sets and volumes 55 
RELEX macro 
exclusive control 157 
when sharing data sets 157 
RELSE macro 
defined 129 
_ to terminate buffer processing 119 
reorganization of indexed sequential data set 183 
reorganization statistics (ISAM) 39 
REREAD option 56, 57 
restart end-of-volume exit routine 94 
restriction with 2540 
restrictions 
on ASCII records 
on 7-track tape 29 
on chained scheduling with 
calculating record length 117 
CNTRL macro 115 
DOS checkpoint records 115 
format-D records 23 
partitioned data set 144 
SKP option 78 
spooled data sets 115 
track overflow 117 
3525 Card Punch 115 _ 
on CNTRL macro ee 
with BSP macro 203 Ree of 
with chained scheduling 115 
with DOS checkpoint records 201 
on DCB usage 48-49 
on DCBD macro usage 46 
on DOS checkpoint records 115, 201-204 
on format-D records with chained scheduling 23 
on ISO/ANSI records 
block prefix 23 
on ISO/ANSI/FIPS records 
block prefix 15, 23 
on NOTE macro with 
BSP macro 203 
multivolume data sets 203 
on POINT macro with 
BSP macro 203 
multivolume data sets 204 
on reading concatenated data sets backward 114 
on user label exit routines 82-86 
resume load 38, 163, 166, 183 
retrieving a generation 199 
return codes 
with block count exit 94, 95 
with user labels 84 
RETURN macro 
relationship in SYNAD routine 78 
REWIND option 
for CLOSE macro 52 
for FEOV macro 57 
RKP (relative key position) operand (DCB _— | 
macro) 163, 185, 186 | 











{ 





RLSE parameter 
DD statement 533 
RORGI, RORG2, RORG3 fields of the DCB 184 
routing data sets through the input/output 
stream 105-107 
RPS (rotational position sensing) 
restriction with track overflow records 
variable-length records 18 
when calculating record length 117 
RO record 6, 150 


save area 
user totaling 87 
scan mode 38 
for QISAM 
issuing PUTX 176 
scheduling of input/output streams 105 
SDW (segment descriptor word) 
format-S records 24 
search option, extended 153 
secondary storage 
See data set storage, direct access storage, magnetic 
tape volumes 
security 205, 206 
segment 
buffer 119, 123 
control code 21 
descriptor word 
for spanned records 21 
indicating a null segment 22 
null 22 
segment descriptor word (SDW) 
format-S records 24 
selecting an access method 35, 36 
sequential data set 
See also BPAM, BSAM, and QSAM data sets 
creation 109,110 
extending 113 
retrieving 110 
updating 112 
sequential organization 
defined 2 
device control 201-204 
device independence 58-59 
SETL macro 
in EODAD routine 76, 77 
when sharing a data set 71 
SETPRT macro 
changing printer control information 202 
relationship with 3800 printing subsystem 202 
SETPRT routine 95 
sharing data sets 69-71 
simple buffering 
description 124-128 
with parallel input processing 66, 67 
SKP option 78 











SMSI operand (DCB macro) 189 
SMSW operand (DCB macro) 188 
space allocation 
BPAM data set 37 
estimating requirements 218-22] 
for a direct data set 150 
for a partitioned data set 135, 136 
for an indexed sequential data set 166-174 
QISAM data set 39 
specifying 217-218 
spanned records 
basic direct access method 22 
considerations for 20 
logical record interface 20 | 
restriction with parallel input processing 67 
restriction with SYSIN data sets 21,106 
sequential access method 19 
variable-length 19 
spooling of SYSIN and SYSOUT data sets 
how to 105-107 
restriction 115 
stacker selection | 
control characters for 14, 31, 214 
STACK operand 31 
using CNTRL macro 201 
STAE exit 157 
STAI exit 157 
standard format for fixed-length records 14 | 
standard labels | 
direct access volumes 6, 209 
magnetic tape volumes _ 5, 8 | 
statistics reorganization (ISAM) 39 
storage | 
See direct access storage, magnetic tape volumes 
STOW macro | 
description 141 | “s 
restriction with DCB abend exit 97. 
when sharing a data set 71 | 
subpool 0, when shared 157 
substitute mode 
defined for buffering 124 
switching, volume 
automatic : 
restriction with concatenated data sets 114 
with end-of-volume 56 | 
with FEOV macro 57 
with GET macro 65 
initiated by CHECK 64 
SYNAD field, programming consideration 59 
SYNAD routine 
changing address in DCB 46 
description 77-79 
macros used in 72, 73 
programming consideration 59 
relationship with DECB 65 | 
relationship with SETL option 191 
relationship with SYSIN/SYSOUT data sets 107 
temporary close restriction 52 | : 
when adding records to ISAM data set 183 
when sharing a data set 72 
with basic access technique 61 
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with queued access technique 65 description 7 jos 


SYNADAF macro _ restriction of BSP macro 203 Me 
description 72, 73 | restriction with BDAM_ 156 - 
examples 111 restriction with parallel input processing 67 
use in SYNAD routine 79 restriction with RPS feature 117 

SYNADRLS macro restriction with variable-length records 18 
description 73 track addressing, relative 
examples 111 BDAM 36 
use in SYNAD routine 79 track overflow 

SYNCDEV macro 204 restrictions 

synchronous error routine exit ISAM 38 
See SYNAD routine trailer labels 

SYSIN data set user 82, 86 
FEOV macro ignored for 58 TRC (table reference character 3800) 19 
restriction with TRTCH operand (DCB macro) 30 

chained scheduling 115 TRUNC macro 

parallel input processing 67 description 129 

spanned variable-length records 21 to terminate buffer processing 119 

user totaling 86 truncated blocks, format-F records 15 
routing data through input stream 105-107 truncated format-U record 28 

SYSOUT data set TTR 
FEOV macro ignored for 58 See address, direct access storage device, relative 
restriction with TYPE=T operand 52-55 


chained scheduling 115 
label exits 85 


spanned variable-length records 21 , 
user totaling 86 # 


routing data through output stream 105-107 
system input stream 105-107 
system output stream 105-107 U-format records 


system output writer 105-107 See format-U records ee 
SYSI].IMAGELIB UCS (universal character set) image 


relationship with SETPRT 202 


adding band names/aliases 202 
UHL (user header label) 82-86 


character arrangement table modules 202 


FCB images 202 unblocking records 
UCS image tables 202 BPAM 37 
UCS images 202 BSAM 38 
SYS1.IMAGELIB data set QISAM = 38 
search of 95 | QSAM 39 
undefined length records 
See format-U records 
, UNIT operand 
DD statement 45 
| unlabeled magnetic tape 5-9 
. UPDAT option 
table reference character See also update mode 
See TRC EODAD routine entered for BSAM_ 76 
table reference character (3800) 31, 32 opening a dataset 42 
tape restriction with 
See magnetic tape volumes, paper tape reader | SYSIN/SYSOUT data sets 51 
tapemarks 9 updating a sequential data set 112 
temporary close 52-55 with spanned records 20 
totaling area, user totaling exit routine 86-87 update mode 
track See also UPDAT option 
addressing 7 | with format-U records 28 
defined 6 with PUTX 124 
format with simple buffering 127 
count data format 6 user catalog 10 > 
count key data format 6 user header label (UHL) 82-86 eG 
index 159-162, 166 user label exit routine ay 
overflow option description 82-86 
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exit list entry 83 


restriction for data sets on volumes without standard 


labels 85 

restriction for SYSOUT data sets 85 

with read backward 83, 85 
user totaling exit routine 

description 86-87 

exit list entry 86 

how specified 86 

image area address 87 

relationship with end-of-volume exit 94 

restricted to BSAM, QSAM_ 86 

Save area 87 

totaling area 86-87 

variable-length and spanned records 87 
user trailer label (UTL) 82-86 
utility programs 

IDCAMS 218 

IEBCOPY 146 

IEHATLAS = 73 

IEHLIST 189 

IEHMOVE — 134 

IEHPROGM 167, 198 

initializing direct access volume 6 
UTL (user trailer label) 82-86 


V-format records 
See format-V records 
validation suppression exit 51] 
variable-length record (format-D) 23-24 
variable-length record (format-S) 23-24 
variable-length record (format-V) 
description 18 
segments 18,19 
spanned 
description 19-23 
restrictions with SYSIN and SYSOUT data 
sets 21 
special considerations, with user totaling 87 
with parallel input processing 66 
version increment of generation data group 194 
version number field 
Version 3 labels 196 
VIO data set 36 


volume 
defined 5 
disposition 


See DISP operand 
identification operand (DD statement) 45 


index 

See index 
initializing 6 
labels 











See labels, direct access 
magnetic tape 
See magnetic tape volumes 
positioning 52-57 
switching 357, 65, 114 
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